开发 环境 
基础 

环境 

配置 

架构 
事件 和 属性 
输入 管理 
控件 

图 形 

语言 

开发 环境 
Windows 打包 
Android 
Android 打包 
Android 虚拟 机 
Mac 打包 

iOS 打包 
协议 相关 


Bug-Garden on Mac 


目录 


Kivy 中 文 编程 指南 


Kivy 十 什么 ? 


Kivy 是 一 个 开源 的 Python 框架 ， 用 于 快速 开发 应 用 ， 实 现 各 种 当前 流行 的 用 户 界面 ， 比 如 多 


点 触摸 等 等 。 

Kivy 可 以 运行 于 Windows > Linux’ MacOS > Android > iOS 等 当前 绝 大 部 分 主流 桌面 / 移 
动 端 操作 系统 g 

Kivy 基于 Python ， 界 面 文件 和 程序 文件 相互 分 离 的 设计 思路 ， 设 计 简洁 优雅 ， 语 法 易学 ， 适 
合 新 人 入 门 。 

目前 Kivy 的 官方 文档 还 不 算 很 完善 ， 中 文 翻译 版 本 之 前 也 有 过 ， 但 往往 没有 进行 持续 更 新 ， 
或 者 内 容 和 覆盖 不 全 面 ， 所 以 我 们 这 次 来 一 个 长 期 持久 的 跟 进 。 同 时 期 待 你 的 参与 ! 


如 果 你 想 参 与 进来 ， 可 以 加 入 我 们 的 Kivy 交流 QQ 群 号 :248136053， 也 可 以 关注 我 的 [ 知 乎 专 
栏 ](https://zhuanlan.zhihu.com/python-kivy) 


从 去 年 开始 的 Kivy 编程 指南 中 文 翻译 项 目 ， 今 天 基本 算是 弄 完 了 ， 把 Kivy Programming 
Guide 里 面 的 全 部 内 容 翻 译 了 一 遍 。 


当然 了 ， 质 量 还 是 不 怎么 样 好 ， 所 以 希望 大 家 多 批评 指正 ， 我 会 尽快 改正 。 


E, 
然后 开始 翻译 文档 的 时 候 ， 也 还 是 容易 经 常 变 得 很 暴躁 ， 尤 其 是 遇 到 一 些 原文 的 语法 错误 、 
逻辑 错误 、 自 己 鬼 扯 也 扯 不 通顺 的 地 方 等 等 。 


但 是 后 来 我 逐渐 地 开始 钦佩 这 些 创 建 了 Kivy 的 人 们 ， 我 意识 到 他 们 也 跟 我 一 样 是 一 群 热爱 
Python 的 人 ， 想 为 更 多 的 同样 使 用 Python 的 开发 者 提供 一 个 完整 的 工具 链 ， 以 便于 能 更 简 
洁 轻 快 地 实现 跨 平台 开发 。 

所 以 ， 我 觉得 Kivy 是 一 个 因为 热爱 而 驱动 去 追寻 自由 的 项 目 ， 这 也 让 我 逐渐 对 Kivy 产生 了 更 
多 的 好 感 。 

事 到 如 今 我 可 能 并 不 一 定 会 有 机 会 深入 使 用 Kivy 去 开发 ， 也 依然 希望 Kivy 能 够 发 展 壮大 ， 生 
根 发 芽 ， 开 花 散 种 ， 给 更 多 的 跟 我 一 样 初 入 门 无 所 适 从 的 新 手 一 个 友好 又 高 效 的 选择 。 

我 对 Kivy 官方 文档 的 翻译 ， 暂 告 一 段落 。 后 面 的 API 翻译 ， 有 一 位 知 乎 上 的 朋友 表示 有 兴趣 


进行 ， 一 位 非常 年 轻 有 为 的 少年 。 看 到 现在 的 青少年 人 都 有 如 此 的 学 习 动 力 和 探索 精神 ， 不 
由 得 让 我 感慨 时 代 发 展 之 快 ， 自 己 奔 四 的 路 上 ， 还 有 幸 结 识 了 众多 初 升 的 太阳 。 我 相信 他 们 


BRAVA HE > ABET RR BAG © 


Title: Kivy CN Date: 2017-02-12 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 我 为 什么 对 Kivy 官 方 文档 
进行 翻译 


从 去 年 开始 ， 我 陆续 翻译 了 一 些 Kivy 官 方 文档 中 的 开发 指南 的 内 容 ， 地 址 在 这 


然后 我 又 觉得 有 必要 找 一 个 更 大 的 平台 ， 以 便于 能 给 更 多 人 提供 一 点 便利 ， 所 以 我 又 开 了 一 
个 知 乎 专栏 。 


然而 新 年 这 一 阵 ， 我 做 了 个 手术 ， 身 体 状况 不 太 好 ， 感 觉 理 解 能 力 和 表达 能 力也 有 所 下 降 
(其 实 本 来 也 不 行 ) ， 所 以 我 就 想 ， 不 如 按照 之 前 ThinkPython 的 中 文 翻译 那样 ， 直 接 把 翻译 
稿 开源 放 到 Github 吧 ， 地 址 在 这 里 。 虽 然 我 并 没有 想 出 来 这 样 有 什么 更 好 的 。 


接触 Kivy 时 间 不 长 ， 一 年 多 前 最 开始 知道 有 这 个 项 目的 ， 当 时 的 观感 很 差 ， 因 为 遇 到 若干 个 
Bug ， odiis TR E ETE Mob M M M sou A aei 
就 只 有 这 个 了 ， 相 比 之 下 ， 这 个 好 歹 不 那么 庞大 ， 还 是 捍 好 玩 的。 但 也 就 这 样 了 ， 没 有 进 
步 关 注 。 


然后 是 要 写 GeoPython， 一 些 基 础 的 方法 都 实现 了 之 后 ， 遇 到 了 一 些 数学 上 的 问题 ， 然 后 学 
了 一 些 数学 相关 的 内 容 ， 大 概 有 了 解决 思路 之 后 ， 才 意识 到 ，TMD 没 有 GUI 啊 ， 这 样 常规 的 
地 球 科学 领域 的 同行 们 根本 懒得 看 对 不 对 ? A RAP A ee SF to ty HE Bash 3, A 

Powershell 之 下 使 用 iPython 运 行 某 个 脚本 对 不 对 ? 所 以 我 需要 GUI， 然 而 QT 太 庞 大 繁杂 了 ， 
衡量 了 一 下 自己 的 智力 水 平 ， 估 计 至 少 要 花费 半年 才能 大 概 入 门 。 所 以 我 又 捡 起 来 Kivy 了 。 


过 程 中 我 发 现 Kivy 相 关 的 中 文 资料 还 丨 不 多 ， 那 我 就 从 最 基础 的 官方 文档 开始 翻译 一 下 
吧 ， ee eee 还 能 给 人 提供 一 点 有 用 的 参考 ， 哪 怕 一 丁 
点 用 处 也 好 。 


就 像 我 当年 给 人 辅导 研究 生 的 C++ 和 考博 英语 一 样 ， 其 实 也 是 给 自己 的 持续 学 习 找 一 个 持久 的 
动力 ， 也 是 争取 有 一 点 能 够 积攒 努力 产生 一 个 突破 口 。 就 像 我 的 启蒙 老师 许 先生 当年 给 我 讲 
的 庞 中 华 老 前 华 一 样 ， 一 点 一 点 积累 总 会 有 收获 。 


我 这 些 翻译 的 水 平 良 芳 不 齐 ， 其 中 有 些 简 单 的 部 分 ， 我 基本 可 以 直接 进行 双语 转换 ， 这 就 不 
费 什 么 力气 。 WE 有 的 部 分 一 些 术语 名 词 翻译 得 
不 伦 不 类 ， 所 以 我 又 只 能 心虚 地 标记 上 英文 ， 避 免 对 读者 产生 太 严 重 的 误导 。 


但 我 还 是 会 继续 下 去 的 ， 学 习 和 翻译 两 个 过 程 还 不 能 停 下 来 。 我 不 能 因为 自己 现在 三 十 多 岁 
了 而 且 水 平 还 很 差 ， 就 停止 学 习 提 高 的 尝试 ， 因 为 一 旦 停 下 来 ， 就 更 是 一 点 项 望都 没有 了 ， 
那 就 是 直接 向 命运 举 白 旗 投 降 了 。 


虽然 时 代 已 经 不 同 了 ， ian ‘是 很 钦佩 王 江 民 老 前 华 ， 专 注 和 持久 而 创造 了 传奇 。 我 没有 那么 
大 的 野心 ， 也 不 奢求 什么 辉煌 成 就 ， 只 是 觉得 有 生 之 年 ， 做 点 不 后 悔 的 事情 吧 


Title: Kivy Installment Tutorial Date: 2016-12-30 Category: Kivy Tags: Python,Kivy 


Kivy 中 文安 装 指南 


译 者 的 话 : 接触 Python 有 一 段 时 间 了 ， 之 前 翻译 过 ThinkPython2E， 我 也 仍然 还 是 个 很 菜 很 
弱 很 入 门 的 外 行人 。 我 接 下 来 翻译 的 关于 Kivy 的 各 种 内 容 ， 不 出 意外 的 话 也 必 将 充满 了 各 种 
低级 错误 。 如 果 这 些 错误 有 影响 到 大 家 阅读 理解 ， 提 前 表示 一 下 火 意 。 特别 希望 大 家 能 把 错 
ES 
工具 ， 所 以 我 喜欢 做 各 种 探索 ; 我 的 英语 水 平 也 差 ， 不 过 我 喜欢 从 英语 世界 发 现 有 意思 的 事 
物 并 且 分 享 给 中 文 世界 的 朋友 们 。 本 次 翻译 将 仅仅 翻译 官方 正式 版 部 分 的 安装 指南 ， 每 夜 版 
以 及 更 进 阶 的 安装 内 容 ， 不 做 翻译 。 为 什么 呢 ? 一 来 是 我 自身 水 平 有 限 ， 二 来 你 都 折腾 每 夜 
版 了 还 不 好 好 学 英文 还 要 看 别人 翻译 也 太 不 靠 谱 了 对 不 对 ? 


以 下 是 对 Kivy 官方 网 站 安装 文档 部 分 的 翻译 ， 下 面 三 个 链接 是 原文 地 址 : Installation on 
Windows Installation on Linux Installation on Mac OS 


Windows 系 统 安 装 Kivy 指 南 


自从 1.9.1 版 本 开始 ，Kivy 官方 提供 了 二 进 制 wheels 文件 ， 可 以 用 安装 Kivy 以 及 所 需 的 一 切 
依赖 包 到 一 个 已 经 安装 好 的 Python 环境 中 ， 在 下 文 会 有 讲解 。 


此 外 还 有 每 夜 版 wheels 文 件 ， 可 供用 户 安装 ， 或 者 用 于 将 之 前 安装 的 Kivy 更 新 到 新 版 本 ; 另 
外 本 文 的 后 文中 也 会 讲解 如 何 将 Kivy 安 装 到 自 定义 位 置 ， 而 不 是 安装 到 默认 的 site-packages 
文件 夹 。 


特别 注意 


【 译 者 注 : 这 段 内 容 是 对 官方 文档 比较 忠实 的 翻译 和 还 原 ， 其 中 提 到 的 MinGW 和 Python3.5 的 
兼容 问题 ， Wn o AM ， 因 为 没有 Windows 的 机 器 。 在 Mac 和 Linux 上 3.5 和 
3.6 都 成 功 安 装 了 Kivy， 运 行 过 程 也 没 发 现 问题 。】 


目前 因为 MinGW 和 Python3.5 的 兼容 问题 ， 在 Windows 平 台 上 还 没有 办 法 通过 Python3.5 来 使 
用 Kivy， 至 少 相当 一 段 时 间 内 是 没 指 望 了 ， 更 多 细节 参考 这 里 的 这 个 issue。 想 要 解决 这 个 问 
题 ， 需 要 用 MSVC 来 编译 的 3.5， 不 过 目前 还 没 能 实现 ， 所 以 如 果 你 搞定 了 MSVC 编 译 的 话 一 
定 反 馈 一 下 。 


必要 前 提 


要 使 用 Kivy， 首 先 就 得 安装 Python。Python 有 好 多 版 本 ， 你 可 以 同时 安装 其 中 的 好 多 个 ， 如 
果 你 在 其 中 某 一 个 版 本 的 Python 里 面 要 使 用 Kivy， 就 要 在 这 个 版 本 里 面 单独 按照 一 次 Kivy， 其 
他 版 本 要 使 用 Kivy 需 要 另外 再 进行 安装 ， 就 是 说 每 一 次 安装 Kivy 只 对 一 份 Python 环境 有 效 。 

`> cd isi 
AC lE 
安装 了 Python 之 后 ， 打 开 命 令 行 工 具 cmd， 然 后 按照 下 面 的 命令 来 进行 Kivy 的 安装 。 


1 首先 要 保证 已 经 安装 了 最 新 的 pip 和 wheel : 


python -m pip install --upgrade pip wheel setuptools 


2 然后 安装 必要 的 依赖 包 ( 其 中 gstreamer 大 小 接近 90MB， 如 果 不 需要 用 ， 就 可 以 跳 过 不 安装 
这 个 包 : 


python -m pip install docutils pygments pypiwin32 kivy.deps.sdl2 kivy.deps.glew 
python -m pip install kivy.deps.gstreamer --extra-index-url https://kivy.org/downloads 
/packages/simple/ 


3 如 果 上 一 步 都 成 功 了 没什么 报错 ， 就 可 以 按照 Kivy 了 : 


python -m pip install kivy 


4 在 环境 变量 中 添加 一 些 路 径 到 PATH 来 避免 遇 到 各 种 issues (在 你 的 python.exe 所 在 的 路 径 下 
运行 下 面 的 命令 ): 


set PATH=%PATH%;%cd%\Share\sd12\bin;%cd%\share\glew\bin 


到 现在 为 止 就 搞定 了 ， 你 就 可 以 在 这 份 Python 环 境 中 通过 import kivy 命 令 来 导入 和 使 用 Kivy 
了 。 


特别 注意 


如 果 你 遇 到 了 permission denied 或 者 访问 被 拒绝 之 类 的 错误 提示 ， 你 可 以 试 试 以 管理 员 权 限 
来 运行 命令 行 工 具 cmd 。 


Linux 系 统 安 装 Kivy 指 南 


使 用 包 管 理 器 进行 安装 


本 节 是 给 各 种 发 行 版 用 对 应 的 deb 或 者 rpm 之 类 的 包 进 行 安 装 s .deb/.rpm/... 
Ubuntu / Kubuntu / Xubuntu / Lubuntu (13.10 Saucy 
Salamander 以 及 之 后 更 新 的 版 本 ) 

1 首先 要 根据 你 的 喜好 来 选择 一 个 PPA 源 添加 到 你 的 系统 


( 译 者 注 : 这 里 稳定 版 和 每 夜 版 二 选 一 就 可 以 ， 如 果 要 体验 最 新 特性 ， 可 以 使 用 每 夜 版 ， 但 
是 如 果 用 于 长 期 使 用 追求 稳定 ， 推 荐 用 稳定 版 ， 二 者 千 万 不 要 同时 添加 ， 避 免 出 现 混乱 和 错 


误 。) 


sudo add-apt-repository ppa:kivy-team/kivy # 稳 定 版 
sudo add-apt-repository ppa:kivy-team/kivy-daily 


2 然后 就 要 用 包 管 理 器 来 更 新 一 下 包 列 表 了 : 


sudo apt-get update 


3 更 新 列表 完毕 之 后 ， 如 果 没有 错误 ， 就 可 以 安装 了 : 


sudo apt-get install python-kivy #Python2 M24 
sudo apt-get install python3-kivy #Python3 3Jm- 
sudo apt-get install python-kivy-examples # 可 选 的 1 


Debian (8.0 Jessie 或 者 更 新 的 版 本 ) 


特别 注意 
Debian 7 Wheezy 已 经 不 支持 了 ， 你 至 少 要 升级 到 Debian 8 Jessie 才能 安装 Kivy。 


1 通过 Synaptic 新 立 得 包 管理 器 把 下 面 的 PPA 源 添加 到 你 的 Sources.list 列 表 中 ， 手 动 添 加 也 可 
VA: 


e Jessie/Testing: 


deb http://ppa. launchpad.net/kivy-team/kivy/ubuntu trusty main 


deb http://ppa. launchpad.net/kivy-team/kivy-daily/ubuntu trusty main 


e Sid/Unstable: 


deb http://ppa. launchpad.net/kivy-team/kivy/ubuntu utopic main 


HILHA: 


deb http://ppa.launchpad.net/kivy-team/kivy-daily/ubuntu utopic main 


2 添加 了 源 之 后 ， 就 是 要 添加 一 些 GPG key 到 你 的 apt keyring 里 面 了 ， 运 行 下 面 的 命令 : 


sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys A863D2D6 


"n1 


apt-key adv --keyserver keyserver.ubuntu.com --recv-keys A863D2D6 


3 然后 跟 Ubuntu 里 面 那个 类 似 ， 更 新 列表 完毕 之 后 ， 如 果 没有 错误 ， 就 可 以 安装 了 : 


sudo apt-get update | TUK AF S 

sudo apt-get install python- ay. Python2 

sudo apt-get install python3-kivy #Python3 % 

sudo apt-get install python-kivy-examples # 可 选 的 样 例 代码 


Mint/Bodhi/Suse/Gentoo 这 部 分 省 略 


Mint 的 安装 基本 与 对 应 的 Ubuntu 版 本 一 样 ，Bodhi 估 计 用 的 人 不 多 我 懒得 翻译 了 ， 
OpenSuse/Gentoo 的 用 户 应 该 比较 有 经 验 了 还 用 得 着 我 翻译 么 ? 


Fedora 


1 在 终端 里 添加 repo( 注 意 版 本 不 要 弄 错 ): 


sudo yum-config-manager  --add-repo-http://download.opensuse.orgN 
/repositories/home:/thopiekar:/kivy/Fedora 18/home:thopiekar:kivy.repo 


sudo yum-config-manager --add-repo=http://download.opensuse.org\ 
/repositories/home:/thopiekar:/kivy/Fedora 17/home:thopiekar:kivy.repo 


sudo yum-config-manager --add-repo=http://download.opensuse.org\ 
/repositories/home:/thopiekar:/kivy/Fedora 16/home:thopiekar:kivy.repo 


2 跟 Ubuntu 和 Debian 里 面 一 样 ， 添 加 源 之 后 还 是 要 用 包 管 理 器 更 新 一 下 包 列 表 。 


3 更 新 列表 之 后 通过 包 管 理 器 就 可 以 安装 python-Kivy 和 python-Kivy-examples 了 。 


在 虚拟 环境 中 安装 


必 备 的 依赖 包 


Cython 


一 定 要 注意 ， 这 里 超级 重要 ， 不 同 版 本 的 Kivy 只 能 用 特定 版 本 的 Cython 配 合 才能 使 用 ， 二 者 
一 定 要 匹配 ， 关 系 如 下 表 : 


Kivy Cython 
1.8 0.20.2 
1.9 0.21.2 
1.9.1 0.23 


SDL2 框 加 相关 的 依赖 包 


V. Ubuntu 7j 44] 


在 下 面 的 命令 样 例 中 ， 用 python 和 python-dev 就 表明 是 给 Python2 安 装 ， 而 python3 和 
python3-dev € 41 eI Python355 ° 


H 先 要 安装 这 些 必 备 的 组 件 ， 注 意 上 面 刚 提示 过 ， 如 果 要 用 Python3， 在 python 后 面 如 上 一 个 3 就 可 以 了 : 
sudo apt-get install -y \ 
python-pip \ 
build-essential \ 

git \ 

python \ 

python-dev \ 

ffmpeg \ 

libsdl2-dev \ 
libsd12-image-dev \ 
libsdl2-mixer-dev \ 
libsdl2-ttf-dev \ 
libportmidi-dev \ 
libswscale-dev \ 
libavformat-dev \ 
libavcodec-dev \ 
zlibig-dev 


特别 注意 

在 某 些 特定 的 Linux 版 本 上 ， 你 可 能 会 收 到 一 个 与 fmpeg 包 有 关 的 错误 信息 。 这 种 情况 下 ， 就 
可 以 用 libav-tools 替 换 掉 上 文 命令 中 的 fmpeg， 另 一 种 解决 方法 是 使 用 ppa 来 安装 fmpeg， 使 
用 的 命令 如 下 所 示 : 


sudo add-apt-repository ppa:mc3man/trusty-media 
sudo apt-get update 
sudo apt-get install ffmpeg 


要 在 虚拟 环境 中 安装 Kivy 了 
首先 要 确保 Pip, Virtualenv 和 Setuptools 这 几 个 包 都 更 新 到 最 新 : 


sudo pip install --upgrade pip virtualenv setuptools 


然后 创建 一 个 名 为 "kivyinstall" 的 新 的 虚拟 环境 ， 这 时 候 你 有 两 种 选择 : 


e 第 一 种 是 用 系统 自 带 的 默认 Python 解释 器 : 


virtualenv --no-site-packages kivyinstall 


e 第 二 种 是 设 定 一 个 指定 位 置 的 Python 解释 器 ， 这 里 举例 就 假设 要 用 的 解释 器 路 径 在 
/usr/bin/python2.7 


virtualenv --no-site-packages -p /usr/bin/python2.7 kivyinstall 


建立 好 虚拟 环境 之 后 ， 就 是 进入 里 面 了 : 


. kivyinstall/bin/activate 


千 万 要 注意 ， 这 里 要 安装 正确 的 Cython 版 本 : 


pip install Cython==0.23 


然后 就 可 以 在 这 个 虚拟 环境 里 面 安 装 Kivy 的 稳定 版 了 : 


pip install kivy 


如 果 要 用 开发 版 本 的 Kivy， 就 换 成 下 面 的 命令 来 安装 : 


pip install git-https://github.com/kivy/kivy.gitQmaster 


古老 的 PyGame 相 关 的 依赖 包 


Ubuntu 系统 
首先 还 是 要 安装 一 大 堆 必 要 的 系统 组 件 了 : 


sudo apt-get install -y \ 
python-pip \ 
build-essential \ 
mercurial \ 

git \ 

python \ 

python-dev \ 

ffmpeg \ 
libsdl-image1.2-dev \ 
libsdl-mixeri.2-dev \ 
libsdl-ttf2.0-dev \ 
libsmpeg-dev \ 
libsdli.2-dev \ 
libportmidi-dev \ 
libswscale-dev \ 
libavformat-dev \ 
libavcodec-dev \ 
zlibig-dev 


Fedora 系统 
Fedora 系统 就 要 用 yum 来 实现 组 件 安装 : 


sudo yum install \ 
make \ 

mercurial \ 

automake \ 

gcc \ 

gcc-c++ \ 
SDL_ttf-devel \ 
SDL_mixer-devel \ 
khrplatform-devel \ 
mesa-libGLES \ 
mesa-libGLES-devel \ 
gstreamer-plugins-good \ 
gstreamer \ 
gstreamer-python \ 
mtdev-devel \ 
python-devel \ 


python-pip 


OpenSuse 系统 


^ 2, 


这 里 示范 的 是 用 zypper 作 为 包 管 理 器 : 


sudo zypper install \ 
python-distutils-extra \ 
python-gstreamer-0_10 \ 
python-enchant \ 

gstreamer -0_10-plugins-good \ 
python-devel \ 

Mesa-devel \ 


python-pip 


sudo zypper install -t pattern devel_C_C++ 


然后 又 到 了 在 虚拟 环境 中 安装 Kivy 的 时 候 了 
首先 要 确保 Pip, Virtualenv 和 Setuptools 这 几 个 包 都 更 新 到 最 新 : 


sudo pip install --upgrade pip virtualenv setuptools 


然后 创建 一 个 名 为 "kivyinstall" 的 新 的 虚拟 环境 ， 这 时 候 你 有 两 种 选择 : 


e 第 一 种 是 用 系统 自 带 的 默认 Python 解释 器 : 


virtualenv --no-site-packages kivyinstall 


e 第 二 种 是 设 定 一 个 指定 位 置 的 Python 解释 器 ， 
/usr/bin/python2.7 


virtualenv --no-site-packages -p /usr/bin/python2.7 kivyinstall 


建立 好 虚拟 环境 之 后 ， 就 是 进入 里 面 了 : 


. kivyinstall/bin/activate 


千 万 要 注意 ， 这 里 要 安装 numpy 以 及 正确 的 Cython 版 本 : 


pip install numpy 
pip install Cython==0.23 


里 举例 就 假设 要 用 的 解释 器 路 径 在 


这 里 注意 ， 如 果 你 不 想 用 sdl2， 而 想 要 用 pygame， 你 可 以 通过 export USE_SDL2=0 来 强制 使 
用 pygame。 这 样 一 来 ，Kivy 在 安装 过 程 中 找 不 到 sdl2 的 链接 ， 就 会 自动 设置 这 


尝试 用 pygame 来 构建 。 


pip install hgthttp://bitbucket.org/pygame/pygame 


接 下 来 就 可 以 在 这 个 虚拟 环境 里 面 安装 Kivy 的 稳定 版 了 : 
pip install kivy 
如 果 要 用 开发 版 本 的 Kivy， 就 换 成 下 面 的 命令 来 安装 


pip install git+https://github.com/kivy/kivy.git@master 


虚拟 环境 中 安装 额外 的 包 


在 该 虚拟 环境 中 安装 开发 版 的 buildozer : 


pip install git+https://github.com/kivy/buildozer.git@master 


安装 开发 版 plyer 


个 值 为 0， 然 后 


pip install gitt+https://github.com/kivy/plyer.git@master 


其 他 的 两 个 可 能 用 到 的 包 


pip install -U pygments docutils 


Kivy 官 方 提 供 的 样 例 代码 中 有 一 些 是 可 以 在 安装 配置 好 Kivy 环 境 后 立即 就 能 运行 的 ， 这 些 例子 
就 集成 在 Kivy 包 之 内 。 所 以 ， 如 果 你 要 尝试 这 些 样 例 ， 你 得 实现 确定 好 easy_install 把 你 当前 
在 用 的 Kivy 安 装 到 了 哪里 : 


python -c "import pkg_resources; print(pkg_resources.resource_filename('kivy', '../sha 
re/kivy-examples'))" 


然后 估计 你 会 得 到 一 个 路 径 了 ， 类 似 下 面 这 样 : ( 译 者 注 : 这 个 路 径 是 根据 上 面 那个 命令 来 
答 出 的 ， 每 个 人 不 同 配置 都 产生 不 同 结果 ， 千 万 别 无 脑 复制 哦 ! ) 


/usr/local/lib/python2.6/dist-packages/Kivy-1.0.4 beta-py2.6-linux-x86 64.egg/share/ki 
vy-examples/ 


后 你 知道 位 置 了 ， 就 进入 这 个 路 径 ， 然 后 运行 一 下 样 例 吧 。 比如 你 可 以 尝试 一 下 触 控 追踪 
的 as : 
cd «path to kivy-examples # 把 这 里 替换 成 你 自己 的 kivy-examples 目 录 


cd demo/touchtracer 
python main.py 


这 还 有 一 个 图 片 示意 程序 pictures : 


cd «path to kivy-examples # 把 尖 括 号 内 容 蔡 换 成 你 自己 的 kivy-examples 目 录 
cd demo/pictures 
python main.py 


If you are familiar with Unix and symbolic links, you can create a link directly in your home 
directory for easier access. For example: 


如 果 你 对 Unix 和 符号 链接 比较 熟悉 ， 你 可 以 把 这 个 目录 在 你 的 home 目 录 里 面 创建 一 个 链接 ， 
这 样 以 后 访问 更 方便 ， 举 例如 下 : 


1 通过 上 面 演 示 过 的 命令 获取 样 例 代码 所 在 位 置 ; 


2 把 获取 的 路 径 补 齐 到 下 列 命令 中 ， 然 后 粘贴 到 终端 中 : 


In -s «path to kivy-examples ~/# 把 尖 括 号 内 容 蔡 换 成 你 自己 的 kivy-examples 目 录 
cd ~/kivy-examples 


3 接 下 来 你 就 可 以 用 如 下 这 种 特别 简单 的 方式 来 访问 样 例 代码 了 : 


cd ~/kivy-examples 


如 果 你 想 更 省 事 ， 把 Kivy 程 序 当 做 常规 脚本 来 运行 (比如 输入 ./main.py) ， 或 者 双击 来 运 
行 ， 你 就 需要 创建 一 个 正确 的 Python 链接 。 例 如 下 面 这 样 : 


sudo ln -s /usr/bin/python2.7 /usr/bin/kivy 


或 者 如 果 你 想 要 在 某 个 虚拟 环境 中 运行 Kivy， 那 给 对 应 该 环境 的 Python 做 个 链接 就 行 了 : 


sudo ln -s /home/your username/Envs/kivy/bin/python2.7 /usr/bin/kivy 


还 没完 ， 接 下 来 你 还 要 在 每 一 个 main.py 的 开头 添加 如 下 内 容 作 为 第 一 行 : 


/usr/bin/kivy 


特别 注意 


一 定 要 小 心 哈 ，Windows 系 统 下 的 Python 保存 的 文件 结尾 类 型 很 可 能 是 (CR-LF)，Linux 系 统 
不 会 忽略 掉 其 中 的 <CR， 并 且 依 然 当 做 文件 名 字 的 一 部 分 来 读 取 。 这 就 会 导致 很 多 乱 七 八 错 
的 出 错 信息 ， 所 以 记得 先 确定 把 文件 转换 成 Unix 风 格 的 结尾 。 


设备 权限 


当 你 启动 app 的 时 候 ，Kivy 会 用 到 Mtdev 来 搜索 是 否 有 可 用 的 多 指 触 摸 设 备 ， 如 果 找 到 就 拿 来 
用 作 输 入 。 然 而 这 类 设备 的 使 用 权 通 常 都 被 严格 限制 到 了 特定 的 用 户 或 者 用 户 组 。 


如 果 你 的 用 户 没 有 这 些 权 限 ，Kivy 就 会 记 下 一 个 错误 ， 然 后 给 出 一 个 与 这 些 设备 相关 的 警告 ， 
大 概 如 下 所 示 : 


Permission denied: '/dev/input/eventx' 


所 以 你 要 使 用 这 些 信 息 ， 就 必须 赋予 当前 用 户 或 者 用 户 组 所 必要 的 权限 。 可 以 通过 如 下 命令 
实现 : 


sudo chmod utr /dev/input/eventX 


上 面 这 个 是 给 当前 用 户 赋予 权限 ， 如 果 要 给 当前 用 户 组 权限 ， 可 以 用 下 面 这 个 命令 实 


= 


sudo chmod gtr /dev/input/eventX 


这 个 授权 是 非 永 久 性 的 ， 这 次 授权 后 可 用 ， 以 后 又 要 重新 授权 才能 用 。 所 以 有 个 更 好 的 永久 
nas ' 就 是 把 当前 用 户 添加 到 有 权限 的 用 户 组 中 。 例 如 ， 在 Ubuntu 系 统 里 面 ， 你 可 以 把 
这 个 用 户 添加 到 input 这 个 用 户 组 : 


sudo adduser $USER input 


特别 注意 


修改 完 用 户 权限 之 后 ， 你 要 注销 然后 再 登录 才能 使 用 这 些 权 限 。 
Lon at m 已 
Mac 和 系统 安装 Kivy 指 南 


使 用 官方 提供 的 Kivy.app 
特别 注意 


官方 提供 的 Kivy.app 仅 仅 适 用 于 OS X 10.7 以 及 更 新 版 本 的 系统 (都 是 64 位 的 ) © oo 
的 系统 以 及 10.7 的 32 位 系统 的 用 户 ， 你 就 只 能 自己 手动 安装 各 种 组 件 了 。 建 议 通 


人 > 3 


homebrew 来 安装 。 


对 OS X 10.7 64 位 版 本 以 及 更 新 版 本 系统 ，Kivy 官 方 提供 了 一 个 Kivy.app 的 包 ， 里 面 集成 好 了 
所 有 需要 的 依赖 包 。 可 以 从 这 个 链接 来 下 载 压缩 包 ， 解 压缩 之 后 就 能 发 现 一 个 名 为 Kivy.app 
的 应 用 文件 。 


要 怎么 安装 呢 ? 具体 思路 如 下 : 


= 


1 从 官网 的 这 个 链接 下 载 压 缩 包 ， 其 中 Kivy2.7z 用 的 是 Python 2， 而 Kivy3.7z 用 的 是 Python 
3。 


2 使 用 解压 缩 工 具 把 压缩 包 进 行 解 压 ， 可 以 试 试 Keka 这 个 应 用 。 


3 4e ARE 48 03 KAY Kivy2.app3 says. app 这 两 个 文件 当中 选择 一 个 ， 重 命名 成 Kivy.app， 复 
制 到 应 用 程序 目录 /Applications 下 ， 这 个 过 程 可 以 在 终端 中 通过 下 面 的 命令 来 实现 


sudo mv Kivy2.app /Applications/Kivy.app 


4 然后 是 创建 一 个 名 为 kivy 的 系统 链接 ， 以 便于 方便 访问 kivy 环 境 来 启动 app : 


ln -s /Applications/Kivy.app/Contents/Resources/script /usr/local/bin/kivy 


5 样 例 代 码 以 及 所 有 常规 的 Kivy 工 具 都 可 以 在 /Applications/Kivy.app/Contents/Resources/kivy 
这 个 目录 里 面 找到 了 。 


6 译 者 注 : 你 完全 可 以 同时 拥有 Kivy2. app， 可 以 不 重 命名 他 们 ， 而 直接 把 这 两 个 
都 复制 到 /Applications/ 下 ， 然 后 用 如 下 方式 分 别 创建 名 为 kivy2 和 kivy3 的 链接 (这样 以 后 你 就 
可 以 通过 kivy2 来 使 用 Python2 版 本 的 Kivy， 而 4 kivy3 来 使 用 Python3 版 本 的 Kivy 了 。 ) 


ln -s /Applications/Kivy2.app/Contents/Resources/script /usr/local/bin/kivy2 
ln -s /Applications/Kivy3.app/Contents/Resources/script /usr/local/bin/kivy3 


现在 你 就 可 以 在 终端 中 用 Kivy 脚 本 文件 来 启动 Kivy 的 app 了 ， 也 可 以 把 你 的 main.py 直 接 搜 到 
终端 中 就 能 运行 了 。 


安装 模块 

OS X 上 的 Kivy 使 用 自己 集成 的 一 个 python 环 境 ， 只 在 你 用 kivy 命 令 的 时 候 才 被 激活 。 所 以 要 
在 这 里 安装 模块 ， 要 在 pip 命 令 前 面 加 上 kivy -m 的 前 级 ， 如 下 所 示 (记得 把 蔡 换 成 你 要 安装 的 
模块 名 ) 


kivy -m pip install <modulename> 


这 些 模块 安装 到 哪里 了 呢 ? 
安装 位 置 在 Kivy.app 目 录 内 的 venv 目 录 下 : 


Kivy.app/Contents/Resources/venv/ 


如 果 你 安装 一 个 二 进 制 的 模块 ， 例 如 kivy-garden， 这 些 二 进 制 文件 就 只 能 在 venv 一 级 以 上 的 
目录 使 用 : 


kivy -m pip install kivy-garden 


E 


上 面 这 个 命令 安装 的 garden 的 链接 库 文 件 ， 只 有 通过 如 下 命令 激活 这 个 虚拟 环境 了 才能 使 
用 : 


source /Applications/Kivy.app/Contents/Resources/venv/bin/activate 
garden install mapview 


deactivate 
二 进 制 文件 安装 


直接 复制 到 /Applications/Kivy.app/Contents/Resources/venv/bin/ 这 个 目录 就 行 了 。 


安装 其 他 框架 


Kivy.app 自 带 了 SDL2 和 Gstreamer 这 两 个 框架 。 要 增加 其 他 的 框架 让 Kivy 使 用 ， 可 以 按照 如 下 
思路 实现 : 

git clone http://github.com/tito/osxrelocator 

export PYTHONPATH=~/path/to/osxrelocator 

cd /Applications/Kivy.app 


python -m osxrelocator -r . /Library/Frameworks/<Framework_name>.framework/ \ 
Qexecutable path/../Frameworks/«Framework name».framework/ 


一 定 要 记得 把 替换 成 你 需要 的 框架 名 。osxrelocator 这 个 工具 是 用 来 改变 框架 中 的 链接 库 目 
录 ， 这 样 就 可 以 让 这 些 框架 可 以 在 Kivy.app 中 使 用 了 。 


启动 任意 一 个 Kivy 应 用 


要 运行 Kivy 应 用 ， 只 要 把 源码 拖 找 到 Kivy.app 图 标 上 ， 就 可 以 了 。 样 例 代码 目录 中 的 任何 
Python 文 件 都 可 以 拿 来 试 试 。 


从 命令 行 启动 


如 果 要 在 命令 行 中 运行 Kivy， 把 Kivy.app 复 制 到 应 用 目录 后 ， 双 击 Make Symlinks script 这 个 
脚本 文件 ， 就 可 以 了 。 要 测试 是 否 成 功 ， 可 以 按照 如 下 方式 : 


1 打开 终端 ， 输 入 : 


kivy 


你 就 应 该 能 得 到 一 个 Python 解释 器 环境 了 。 


2 然后 在 这 个 Python 解释 器 内 输入 如 下 代码 : 


import kivy 


如 果 什 么 反应 都 没有 ， 没 有 出 错 ， 那 就 说 明 摘 定 了 。ut errors, it worked. 


3 经 过 上 面 的 验证 ， 说 明 配 置 成 功 了 。 这 样 在 命令 行 终端 中 运行 Kivy 应 用 就 很 简单 了 ， 只 是 执 
行 一 下 脚本 就 可 以 ， 如 下 所 示 : 


kivy yourapplication.py 


i% M HomeBrew% X Kivy 


使 用 HomeBrew 和 Pip 也 可 以 安装 Kivy， 具 体 步 骤 如 下 所 示 : 


1 首先 要 先 安 装 homebrew， 然 后 安装 必 备 组 件 : 


brew install sdl2 sdl2 image sdl2 ttf sdl2 mixer gstreamer 


2 然后 是 通过 pip 安 装 cython 0.23 和 kivy (一 定 要 注意 ， 要 确保 设置 环境 变量 
USE_OSX_FRAMEWORKS=0 ) 


pip install -I Cython==0.23 
USE_OSX_FRAMEWORKS=0 pip install kivy 


3 如 果 不 想 安 装 稳定 版 而 想 使 用 开发 版 ， 第 二 步 就 要 改 用 如 下 命令 了 : 


USE_OSX_FRAMEWORKS=0 pip install https://github.com/kivy/kivy/archive/master.zip 


使 用 MacPorts 和 Pip 来 进行 安装 


特别 注意 


如 果 你 希望 自己 的 Kivy 应 用 能 够 支持 视频 播放 ， 就 得 手动 安装 gstreamer。 可 以 供 过 MacPorts 
来 安装 py-gst-python port. 用 MacPorts 和 Pip 安 装 Kivy 的 过 程 如 下 : 


1 安装 Macports 


2 安装 Python 3.4 并 且 设 定 成 默认 的 : 


port install python34 
port select --set python python34 


3 然后 安装 Pip 并 设置 为 默认 : 


port install pip-34 
port select --set pip pip-34 


4 使 用 Macports 安 装 必 备 组 件 : 
port install libsdl2 libsdl2 image libsdl2 ttf libsdl2 mixer 


5 使 用 Pip 安 装 cython 0.23 和 kivy (一 定 要 注意 ， 要 确保 设置 环境 变量 
USE_OSX_FRAMEWORKS=0) : 


pip install -I Cython==0.23 
USE_OSX_FRAMEWORKS=0 pip install kivy 


6 如 果 不 想 安 装 稳定 版 而 想 使 用 开发 版 ， 第 二 步 就 要 改 用 如 下 命令 了 : 


USE_OSX_FRAMEWORKS=0 pip install https://github.com/kivy/kivy/archive/master.zip 


特别 注意 


如 果 你 在 Mac 系 统 下 使 用 Kivy-Designer 的 时 候 遇 到 如 下 错误 : 


[WARNING ] stderr: from designer.app import DesignerApp 
[WARNING ] stderr: File "/Users/cycleuser/kivy-designer/designer/app.py", 
line 27, in <module> 
[WARNING ] stderr: from kivy.garden.filebrowser import FileBrowser 
[WARNING ] stderr: ImportError: No module named filebrowser 
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Title: Kivy IDE Date: 2017-02-19 Category: Kivy Tags: Python,Kivy 


在 各 种 流行 的 Python IDE 中 配置 Kivy 集成 
开发 环境 


e 英文 原文 


在 Windows 系统 上 配置 PyCharm 使 用 Kivy 
从 1.9.1 开始 ，Kivy 就 可 以 安装 到 你 系统 中 已 有 的 Python 解释 器 中 ， 所 以 在 Windows 系统 
上 面 的 安装 非常 简单 直接 。 


e 1 在 Windows 系统 上 安装 Kivy ; 可 以 参考 英文 原版 安装 指南 或 者 我 博客 里 的 安装 指南 ,或 
者 参考 我 的 知 乎 专栏 。 
。 2 然后 就 在 PyCharm 里 面 建立 或 者 打开 你 的 项 目 就 可 以 了 。 
理论 上 就 这 么 简单 ， 两 步 就 搞定 了 。 如 果 你 有 多 个 Python 解释 器 ， 那 就 需要 选择 安装 了 Kivy 
的 那个 才 行 。 有 具体 步骤 是 在 PyCharm 里 面 ， 按 照 如 下 流程 操作 : 
e 1 File 文件 -> Settings 设置 -> Project 项 目 -> Project Interpreter 项 目 解释 器 


e 2 取消 掉 当 前 的 项 目 解释 器 ， 选 择 你 要 用 的 安装 了 Kivy 的 Python 解释 器 就 好 了 。 


这 就 完毕 了 ， 接 下 来 就 可 以 用 Kivy RAET 


在 macOS 系统 上 配置 PyCharm 使 用 Kivy 


Kivy 开发 团队 推荐 macos 用 户 使 用 homebrew 来 安装 Kivy。 这 很 简单 ， 在 Mac 系统 里 面 打 
F Terminal 终端 就 可 以 了 。 下 面 的 代码 输入 或 者 复制 粘贴 到 终端 提示 符 后 面 就 可 以 了 。 要 注 
意 这 些 代码 特别 长 ， 所 以 可 能 因为 文字 换行 等 等 导致 出 现 多 行 的 情况 ， 这 时 候 一 定 要 注意 要 
复制 完整 。 除 了 用 brew 和 pip 来 安装 Kivy 的 方法 之 外 ， 还 可 以 参考 其 他 的 详细 安装 指南 ， 
比如 我 博客 里 的 安装 指南 或 者 我 的 知 乎 专栏 。 


e 1 安装 Homebrew 


/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/mast 
er/install)" 


e 2 通过 Brew 来 安装 Python 3 


brew install python3 


或 者 Python 2 


brew install python 


e 3 安装 Kivy (FFA E 9 SUE d AE AXE) 。 这 里 一 定 要 注意 ， 下 面 的 
命令 使 用 了 pip3 ， 意 思 是 说 安装 到 了 Python3 里 面 ， 如 果 你 要 用 Python2 ， 那 就 把 下 面 


4 
命令 中 的 pip3 替换 成 pip : 


Sw 


Sw 


brew install hg sdl sdl2 sd12 image sdl2 ttf sdl2 mixer gstreamer 
pip3 install --upgrade pip 

pip3 install cython 

USE OSX FRAMEWORKS-0 pip3 install kivy 


PyCharm 应 该 能 选择 你 默认 的 Python 解释 器 ， 然 后 (估计 差不多 ) 就 是 你 刚刚 把 Kivy 座位 
一 个 模块 来 安装 好 的 那个 解释 器 。 


可 以 通过 下 面 的 路 径 来 对 已 有 模块 进行 检查 : File 文件 -> Settings 设置 -> Project 项 目 -> 
Project Interpreter 项 目 解释 器 


Kivy 语言 自动 补 齐 以 及 代码 高 亮 


1D Bn Xuton 的 一 位 好 心 朋 友 开 发 了 一 个 扩展 文件 ， 可 以 提供 Kivy 语言 的 自动 补 齐 和 代码 高 
安装 方法 如 下 : 


eh 


e 下 载 这 个 文件 ; 

e 打开 Pycharm 的 主 菜单 ， 点 击 File 文件 -> Import 导入 (或 者 Import Settings 导入 设 
E): 

e 选择 刚刚 下 载 的 那个 jar 文件， 然后 PyCharm 会 弹出 一 个 对 话 框 让 你 来 确认 ， 点 击 OK 
就 行 了 。 


。 重新 启动 PyCharm ， 看 看 是 不 是 有 效果 了 ? 


更 多 其 他 IDE 


这 些 我 就 不 翻译 了 ， 大 家 可 以 去 看 看 。 


e How to use Python Tools for Visual Studio to develop and run Kivy Applications 
e kivy-eclipse-and-pydev-also-pypy 
e How to Set up Wing IDE for Kivy on Windows 


开发 环境 


e Kv language definition file for gedit 
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Title: Kivy Basics Date: 2017-01-22 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 基础 知识 


原文 地 址 。 


Kivy 环 境 安 装 搭建 


Kivy 要 依赖 很 多 Python 包 ， 比 如 pygame, gstreamer, PIL, Cairo Mv 。 这 些 包 并 非 
都 是 必需 的 ， 村 平台 来 看 具体 情况 ， 有 时 候 缺 那么 个 包 就 可 能 导致 安装 失 
败 ， 或 者 运行 过 程 中 出 错 等 等 ， 这 就 插 痛 苦 的 。 所 以 Kivy 官 is X 提 供 
了 E 包 ， 解 压缩 之 后 直接 就 能 用 。 具 体 的 安装 过 程 可 以 参考 下 面 链接 中 
的 中 文安 装 指南 : 

e Kivy 中 文安 装 指南 


如 果 你 非 要 自己 从 零 开 始 安装 ， 那 最 起 码 要 确保 安装 有 Cython 和 Pygame。 这 两 个 包 可 以 通过 
pip 来 安装 ， 如 下 所 示 : 


pip install cython 
pip install hgthttp://bitbucket .org/pygame/pygame 
pip install kivy 


Kivy 的 开发 版 本 也 可 以 通过 git 来 安装 : 


git clone https://github.com/kivy/kivy 
make 


创建 一 个 应 用 


创建 一 个 Kivy 应 用 挺 简单 的 ， 大 概 步 骤 如 下 : 


。 基于 App 类 创建 一 个 子 类 ; 
° A APA DM 个 控件 的 实例 也 就 是 你 整个 应 用 的 根 控件 )。 
e 创建 一 个 类 的 实例 ， 然 后 调用 run() 方 法 。 


下 面 的 代码 就 是 上 述 思 路 的 最 小 化 实现 : 


import kivy 
kivy.require('1.0.6') # 注意 要 把 这 个 版 本 号 改变 成 你 现 有 的 Kivy 版 本 号 ! 


from kivy.app import App # 译 者 注 : 这 里 就 是 从 kivy.app 包 里 面 导入 App 类 
from kivy.uix.label import Label 4 译 者 注 : 这 里 是 从 kivy .uix.label 包 中 导入 Label 控 件 ， 这 里 都 注 
意 开 头 字 母 要 大 写 


class MyApp(App): 


def build(self): # 译 者 注 : 这 里 是 实现 Duild( ) 方 法 
return Label(text='Hello world') # 译 者 注 ; 在 这 个 方法 里 面 使 用 了 Labe1 控 件 


ab name == iene 
MyApp().run() # 译 者 注 : 这 里 就 是 运行 了 。 





译 者 注 : 这 一 段 的 额外 添加 的 备注 是 给 萌 新 的 ， 

就 是 要 告诉 萌 新 们 ， 一 定 要 每 一 名 每 一 个 函数 每 一 个 变量 甚至 每 一 个 符号 ， 都 要 读 得 懂 1 | |! 
如 果 是 半 懂 不 懂 的 状态 ， 一 定 得 学 透 了 ， 要 不 然 以 后 早晚 得 补课 . 

这 时 候 又 让 我 想起 了 结构 化 学 。 

总 之 更 详细 的 内 容 后 面 会 有 ， 大 家 加 油 。 


把 上 面 的 代码 以 文本 形式 复制 到 一 个 文本 文件 中 ， 保 存 成 py 文件 ， 例 如 main.py， 然 后 运行 ， 
就 行 了 。 


Kivy 应 用 的 生命 周期 


跟 学 习 开 发 Android 应 用 的 时 候 类 似 ， 咱 们 首先 也 是 要 了 解 一 下 Kivy 应 用 的 生命 周期 (生命 周 
期 图 由 小 涂 汉 化 ) 


NO 


程序 被 调 到 前 台 | Androidstios 


on.resumeQiRBR j- -ool 软件 主体 
执行 on_pause() 时 
外 部 应 用 或 内 部 函数 |. 将 保存 程序 的 状态 
SRS 
on. stop() Hat < 一 
On_pausel0) 函 数 >. >. 


“车 返回 True 









python 程序 停 止 BÉM—————— , 


如 上 图 所 示 ， 不 论 什么 用 途 和 目的 ， 咱 们 应 用 的 入 口 都 是 这 个 run() 方 法 ， 在 本 文 的 样 例 代码 
中 ， 就 是 "MyApp().run()”。 


下 面 就 一 行 一 行 开始 详细 解释 了 : 


from kivy.app import App 


为 什么 要 导入 这 个 App 类 呢 ? 因为 咱们 自 定 义 的 这 个 App 要 继承 这 个 类 。 这 个 类 的 位 置 在 kivy 
安装 目录 下 的 kivy 目 录 下 的 app.py 文 件 中 。 
特别 注意 


如 果 你 想 要 深入 挖掘 一 下 ， 去 了 解 这 个 Kivy 的 App 类 到 底 是 怎么 个 内 容 ， 你 可 以 打开 这 个 
app.py 文 件 ， 亲 自 来 看 看 。Kivy 作 者 特别 鼓励 大 家 去 阅读 源码 。Kivy 基 于 Python， 用 Sphinx 
编写 的 文档 ， 所 以 每 个 类 的 文档 都 在 对 应 的 文件 内 。 


然后 咱们 回 过 头 来 ， 继 续 看 本 文 这 次 的 代码 的 第 二 行 : 


from kivy.uix.label import Label 


这 里 一 定 要 特别 注意 各 种 包 和 类 的 导入 。"kivy.uix" 这 个 包 的 作用 是 容纳 用 户 界面 元 素 ， 比 如 各 
种 输出 布局 和 控件 。 


接 下 来 看 到 这 一 
class MyApp(App): 
这 一 行 定义 了 咱们 这 次 的 Kivy 应 用 的 基 类 。 如 果 你 要 做 修改 的 话 ， 把 MyApp 改 成 你 要 设 定 的 
应 用 名 字 就 可 以 了 。 
接着 往 下 看 : 
def build(self): 


fe bo) A oP 8] 3 E P oo HL S38 8 SB RA > build BAAT Ab AY Z6 3e 3t (140 46 16e 3E LIE TE PF 
的 位 置 。 根 控件 返回 的 操作 在 下 面 这 一 行 中 实现 : 


return Label(text='Hello world') 


这 里 我 们 用 文本 和 ello World' 对 Label 这 一 控件 进行 了 初始 化 ， 并 且 返 回 了 其 实例 。 这 个 Label 
就 是 咱们 这 个 应 用 的 根 控件 了 。 

特别 注意 

Python 是 用 缩 进 来 区 别 代码 块 的 ， 所 以 一 定 要 注意 上 面 代 码 的 缩 进 和 层次 ， 尤 其 是 函数 定义 
那 部 分 

然后 咱们 继续 ， 到 了 站 正 让 应 用 开始 运行 的 这 部 分 了 : 


a name s= U En 
MyApp().run() 





这 里 对 MyApp 这 个 类 进行 了 初始 化 ， 然 后 调用 了 这 个 类 的 run() 方 法 。 这 样 就 初始 化 并 启动 了 
我 们 的 Kivy 应 用 了 。 

Y= /一 x 

运行 应 用 

接 下 来 就 是 要 在 不 同 操作 系统 平台 上 来 运行 咱们 刚刚 写 好 的 应 用 了 : 


To run the application, follow the instructions for your operating system: 


e Linux 终端 中 以 如 下 方式 运行 : 


$ python main.py 


e Windows 可 以 在 CMD 中 以 如 下 方式 运行 : 


$ python main.py # 用 系统 Python 运行 
GEN > # 用 来 运行 ， 注 意 这 里 要 设 定好 正确 的 路 径 


e Mac OS X 跟 Linux 差 不 多 ， 也 在 终端 中 运行 ， 不 过 是 要 用 Kivy 官 方 提供 的 集成 解释 器 : 
$ kivy main.py 


e Android 下 面 要 运行 还 需要 一 些 复 杂 的 文件 ， 所 以 等 以 后 深入 了 之 后 再 给 讲解 这 部 分 了 。 


这 个 应 用 运行 之 后 的 具体 效果 就 是 下 面 图 片 所 示 这 样 ， 会 打开 一 个 窗口 ， 然 后 展示 出 一 个 
Label， 上 面 写 着 文本 'Hello World'， 这 个 Label 会 履 盖 该 窗口 的 全 部 区 域 。 就 这 样 了 。 


Hello world 





修改 定制 这 个 应 用 


接 下 来 咱们 扩展 一 下 这 个 应 用 的 功能 ， 增 加 一 个 用 户 名 /密码 输入 的 页 面 吧 。 


from kivy.app import App 

from kivy.uix.gridlayout import GridLayout 
from kivy.uix.label import Label 

from kivy.uix.textinput import TextInput 


class LoginScreen(GridLayout): 


def init (self, **kwargs): 
super(LoginScreen, self). (init (**kwargs) 
self.cols - 2 
self.add widget(Label(text-'User Name')) 
self.username = TextInput(multiline=False) 
self .add_widget(self.username) 
self .add_widget(Label(text='password')) 
self.password = TextInput(password=True, multiline=False) 
self .add_widget (self .password) 


class MyApp(App): 


def build(self): 
return LoginScreen() 


uif name == mas 
MyApp().run() 





在 下 面 这 行 代码 中 ， 我 们 导入 了 一 种 名 为 Gridlayout 的 布局 : 


from kivy.uix.gridlayout import GridLayout 


个 类 被 我 们 用 作 基 类 来 制作 根 控件 LoginScreen， 在 如 下 代码 中 进行 了 定义 : 


class LoginScreen(GridLayout): 


如 下 代码 中 ， 我 们 在 LoginScreen 类 中 重新 定义 了 初始 化 方法 init()， 这 样 来 增加 一 些 控件 ， 并 
且 定义 了 这 些 控件 的 行为 : 


def dxinaspeesel tes kwatpgsy: 
super(LoginScreen, self). init (**kwargs) 


一 定 要 注意 这 里 要 加 super， 才 能 把 现 有 的 新 初始 化 方法 覆盖 掉 继 承 来 的 上 昌 初 始 化 方法 。 另 外 
也 要 注意 ， 这 里 调用 super 的 时 候 没 有 省 略 掉 **kwargs， 这 是 一 种 好 习惯 。 


然后 继续 往 下 看 : 


self.cols = 2 

self .add_widget(Label(text='User Name')) 

self.username = TextInput(multiline=False) 

self .add_widget (self .username) 

self.add widget(Label(text-'password')) 

self.password - TextInput(password-True, multiline-False) 
self.add widget(self.password) 


上 面 的 代码 中 ， 我 们 让 GridLayout 来 管理 子 控件 ， 把 子 控件 设置 为 两 栏 ， 然 后 加 上 用 户 名 和 蜜 
码 的 Label 字 符 显 示 控 件 和 Textlnput 字 符 输 入 控件 。 


运行 上 面 的 代码 ， 得 到 的 窗口 效果 大 概 如 下 图 : 


User Name 


password 





尝试 着 重新 缩放 一 下 窗口 大 小 ， 你 会 发 现 上 面 的 控件 会 相对 整个 窗口 的 尺寸 而 自行 调整 大 
小 ， 并 不 需要 人 为 去 操作 了 。 这 是 因为 这 些 控件 都 使 用 了 默认 的 尺寸 。 
上 面 这 个 代码 虽然 有 输入 框 ， 但 是 并 没有 提供 用 户 输 入 的 支持 和 处 理 ， 所 以 并 不 能 进行 用 户 


名 /密码 验证 ， 也 没有 任何 其 他 用 处 。 后 续 的 练习 中 咱们 再 来 深入 去 探讨 这 些 功能 ， 并 且 还 会 
讲 一 讲 空间 的 尺寸 和 位 置 等 话题 。 


Title: Kivy Environment Date: 2017-02-5 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 环境 变量 


Kivy 的 初始 化 和 很 多 行为 都 可 以 通过 各 种 环境 变量 来 控制 。 


例如 ， 若 要 严格 设 定 用 PIL 进 行文 本 浑 染 ， 可 以 通过 如 下 方式 来 实现 : 


$ KIVY_TEXT=pil python main.py 


( 译 者 注 : PIL > Python Imaging Library, Python 下 常用 的 绘图 库 ) 


所 有 的 这 说 变量 的 修改 设 定 都 需要 在 导入 Kivy 之 前 进行 ， 具 体 如 下 所 示 : 


import os 
os.environ['KIVY TEXT'] = 'pil' 
import kivy 


路 径 控 制 
e. 从 Kivy1.0.7 版 本 开始 提供 
You can control the default directories where config files, modules and kivy data are located. 
Kivy 的 配置 文件 、 模 块 以 及 数据 存储 的 软 认 目录 ， 都 可 手动 设 定 所 在 位 置 。 
KIVY_DATA_DIR 
这 个 是 Kivy 的 数据 目录 ， 默 认 值 为 /data 。 
KIVY_MODULES DIR 
这 个 是 Kivy 的 模块 目录 ， 默 认 值 为 /modules 。 
KIVY_HOME 


这 个 是 Kivy 的 HOME 目录 ， 该 目录 是 用 来 存放 本 地 配置 文件 的 ， 必 须 是 一 个 可 以 写 入 的 位 置 。 
对 应 不 同系 统 也 有 不 同位 置 : 


* Desktop: /.kivy 
* Android: /.kivy 
* iOS: /Documents/.kivy 


e. 从 Kivy1.9.0 版 本 开始 提供 
KIVY_SDL2_PATH 


这 个 变量 若 设 定 了 ， 编 译 Kivy 的 时 候 就 会 使 用 该 位 置 的 SDL2 库 文件 ， 而 不 再 使 用 系统 的 库 文 
件 。 在 环境 变量 PATH 的 开头 部 位 就 要 设 定好 这 个 变量 ， 这 样 在 运行 一 个 Kivy 应 用 的 时 候 才 能 
也 使 用 相同 的 SDL2 库 文件 。 


e. 从 Kivy1.9.0 版 本 开始 提供 


特别 注意 


刚刚 这 个 SDL2 路 径 是 用 来 编译 Kivy 的 。 运 行程 序 的 话 就 用 不 着 了 。 


配置 文件 


KIVY_USE_DEFAULTCONFIG 
若 设 定 了 此 环境 变量 ，Kivy 会 读 取 制 定 的 配置 文件 。 
KIVY_NO_CONFIG 


若 设 定 了 此 环境 变量 ，Kivy 将 不 会 读 取 也 不 会 写 入 任何 配置 文件 。 也 适用 于 用 户 配置 文件 夹 的 
位 置 。 ( 译 者 注 : 这 名 话 我 还 没 弄 明白 ， 因 为 没有 这 样 尝 试 。) 


KIVY_NO_FILELOG 
若 设 定 了 此 环境 变量 ， 日 志 将 不 再 输出 到 文件 内 。 

KIVY_NO_CONSOLELOG 
若 设 定 了 此 环境 变量 ， 日 志 将 不 再 输出 到 控制 台 。 

KIVY_NO_ARGS 
若 设 定 了 此 环境 变量 ， 命 令 行 传递 的 参数 将 不 会 被 Kivy 解 析 和 使 用 。 也 就 是 说 ， 可 以 不 用 一 


定义 符 ， 就 能 随便 创建 一 个 使 用 自己 参数 的 脚本 或 者 应 用 : 


import os 
os.environ["KIVY_NO_ARGS"] = "1" 
import kivy 


e. 从 Kivy1.9.0 版 本 开始 提供 


限定 Kivy.core 核 心 ， 使 用 特定 版 本 


定 为 某 个 特定 版 本 的 kivy.core。 
KIVY_WINDOW 

这 一 变量 是 用 来 设 定 如 何 创建 窗口 ， 可 用 值 : sdl2, pygame, x11, egl rpi 
KIVY_ TEXT 

这 一 变量 是 用 来 设 定 如 何 泻 染 文本 ， 可 用 值 : sdl2, pil, pygame, sdlttf 
KIVY_VIDEO 


这 一 变量 是 用 来 设 定 如 何 泻 染 视频 ， 可 用 值 : pygst, gstplayer, pyglet, ffpyplayer, ffmpeg, gi, 
null 


KIVY_AUDIO 


这 一 变量 是 用 来 设 定 如 何 播放 声音 ， 可 用 值 : sdl2, gstplayer, pygst, ffoyplayer, pygame, gi, 
avplayer 


KIVY_IMAGE 

这 一 变量 是 用 来 设 定 如 何 读 取 图 像 ， 可 用 值 : sdl2, pil, pygame, imageio, tex, dds, gif 
KIVY_CAMERA 

这 一 变量 是 用 来 设 定 如 何 读 取 摄 像 头 ， 可 用 值 : videocapture, avfoundation, pygst, opencv 
KIVY_SPELLING 

这 一 变量 是 用 来 设 定 拼写 ， 可 用 值 : enchant, osxappkit 
KIVY_CLIPBOARD 


"I E 


这 一 变量 是 用 来 设 定 剪 切 板 管理 组 件 ， 可 用 值 : sdl2, pygame, dummy, android 


设置 单位 
KIVY_DPI 

这 个 是 用 来 设 定 Metrics.dpi 的 dpi 值 的 。 
e. 从 Kivy1.4.0 版 本 开始 提供 
KIVY_METRICS_DENSITY 

这 个 是 用 来 设 定 Metrics.density， 像 素 密度 。 


e 从 Kivy1.5.0 版 本 开始 提供 


KIVY METRICS FONTSCALE 
这 个 是 用 来 设 定 Metrics.fontscale， 字 体 大 小 。 


e. 从 Kivy1.5.0 版 本 开始 提供 


图 形 输 出 


KIVY_GL_BACKEND 

此 变量 用 于 设 定 使 用 的 OpenGL 后 端 ， 更 多 细节 参考 cg|. 
KIVY_GL_DEBUG 

此 变量 用 于 设 定 是 否 对 OpenGL 调 用 进行 日 志 记 录 ， 更 多 细节 参考 cgl. 
KIVY_GRAPHICS 

此 变量 用 于 设 定 是 否 使 用 OpenGL ES2 ， 更 多 细节 参考 cgl. 
KIVY_GLES LIMITS 


此 变量 用 于 设 定 是 否 强 制 设 定 GLES2 (默认 值 为 启用 ， 设 置 为 1) 。 如 果 设 定 为 false，Kivy 将 
不 再 兼容 GLES2。 ( 译 者 注 : 这 部 分 我 不 懂 ， 就 直接 生硬 翻译 了 原文 ， 建 议 大 家 参考 一 下 原 
文 去 理解 。) 如 果 设 置 为 true， 可 能 有 下 表 中 所 示 的 潜在 的 不 兼容 情况 : 


Patel If true, the number of indices in a mesh is limited to 65535 
indices 
When blitting to a texture, the data (color and buffer) format must be the 
same format as the one used at the texture creation. On desktop, the 
Texture f ; : : 
blit conversion of different color is correctly handled by the driver, while on 


Android, most of devices fail to do it. Ref: 
https://github.com/kivy/kivy/issues/1600 


。 从 Kivy1.8.1 版 本 开始 提供 
KIVY. BCM DISPMANX ID 


此 变量 是 针对 Raspberry Pitt RRP SAY > FI Tx E Pp ETE SS HUM at Hs Fo KRUG AO? F 
面 列表 中 是 在 vc_dispmanx_types.h 这 个 头 文件 中 存储 的 可 供 选择 的 变量 值 : 


e 0: DISPMANX ID MAIN LCD 
e 1: DISPMANX ID AUX LCD 

e 2: DISPMANX ID HDMI 

e 3: DISPMANX ID SDTV 

e 4: DISPMANX ID FORCE LCD 
e 5: DISPMANX ID FORCE TV 


e 6: DISPMANX ID FORCE OTHER 


( 译 者 注 : 上 面 0-6 分 别 是 不 同 的 显示 输出 端口 ， 相 信 很 容易 看 懂 ， 大 家 探索 一 下 吧 。 ) 


Title: Kivy Configure Date: 2017-02-6 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 配置 修改 


Kivy 的 配置 文件 是 一 个 名 为 config.ini 的 文本 ， 符 合 标 准 INI 格 式 。 


找到 配置 文件 位 置 
Kivy 的 配置 文件 存放 在 环境 变量 KIVY_HOME 所 制定 的 位 置 


KIVY_HOME>/config.ini 


在 桌面 平台 上 ， 默 认 的 位 置 如 下 : 


HOME_DIRECTORY>/.kivy/config.ini 


所 以 ， 假 设 你 的 用 户 名 是 “tito"， 在 各 个 操作 系统 下 的 配置 文件 位 置 则 如 下 所 示 : 


e Windows: c:\Users\tito\.kivy\config.ini 
e OSX: /Users/tito/.kivy/config.ini 


e Linux: /home/tito/.kivy/config.ini 


( 译 者 注 : 这 里 要 注意 ，tito 只 是 原文 的 一 个 示范 ， 相 当 于 张 三 李 四 这 样 ， 新 手 可 别 照 着 复制 
找 不 到 ， 要 用 自己 操作 系统 中 具体 的 用 户 名 。) 


在 Android 系 统 中 位 置 如 下 : 


ANDROID_APP_PATH>/.kivy/config. ini 


假如 你 的 Kivy 应 用 的 包 名 称 为 “org.kivy.launcher ,那么 该 Kivy 应 用 的 配置 文件 位 于 : 


/data/data/org.kivy.launcher/files/.kivy/config.ini 


在 iOS 上 Kivy 的 默认 配置 文件 位 于 : 


HOME_DIRECTORY>/Documents/.kivy/config.ini 


本 地 配置 


有 时 候 用 户 或 者 开发 者 可 能 需要 针对 特定 的 应 用 来 修改 配置 ， 或 者 对 Kivy 的 某 个 组 件 进 行 测 
试 ， 比 如 输入 模块 之 类 的 。 这 时 候 就 可 以 用 如 下 命令 创建 一 份 新 的 配置 文件 : 


from kivy.config import Config 
Config.read( file>) 
# set config 


Config.write() 


有 时 候 本 地 配置 只 有 一 个 ,ini 文件 还 不 够 用 ， 比 如 说 可 能 你 要 单独 使 用 某 个 garden、Kivy 日 志 
或 者 其 他 什么 模块 ， 这 时 候 就 要 把 KIVY_HOME 这 个 环境 变量 进行 修改 了 ， 指 定 到 目标 位 置 就 


Ns 


> 


import os 
os.environ['KIVY HOME'] = folder> 


还 有 一 种 思路 ， 就 是 在 运行 Kivy 应 用 之 前 ， 在 终端 中 手动 修改 一 下 这 个 环境 变量 : 
1. Windows: set KIVY_HOME=folder> 


2. Linux & OSX: export KIVY_HOME=folder> 


在 设置 了 KIVY_HOME 之 后 ， 所 指定 的 这 个 文件 夹 就 会 被 当做 默认 的 .kivy 文 件 夹 来 用 。 


详细 理解 配置 项 


在 kivy.config 模块 中 可 以 看 到 全 部 的 配置 项 的 解释 。 


Title: Kivy Architecture Date: 2017-02-7 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 架构 概览 


英文 原文 

本 章 我 们 将 从 软件 工程 的 角度 ， 来 简单 介绍 一 下 Kivy 的 设计 。 这 对 于 理解 各 个 部 分 如 何 配合 工 
作 会 有 帮助 。 如 果 你 只 关注 代码 ， 可 能 有 时 候 会 遇 到 这 样 一 种 情况 ， 就 是 你 已 经 有 了 一 个 初 
步 的 想法 了 ， 但 具体 怎么 去 实现 可 能 还 是 一 头 雾 水 ， 所 以 本 章 就 针对 这 种 情况 ， 来 更 深入 地 
讲解 一 下 Kivy 的 一 些 基 本 思想 。 你 也 可 以 先 跳 过 这 一 章 ， 等 以 后 再 翻 回来 看 ， 不 过 我 们 建议 开 
发 者 还 是 先 看 一 下 这 些 内 容 比 较 好 ， 起 码 可 以 快速 略 读 一 下 有 个 印象 。 

Kivy 包 含 的 若干 个 模块 ， 我 们 将 对 这 些 模块 一 一 进行 简要 说 明 。 下 面 这 幅 图 是 Kivy 整 个 架构 的 
概括 图 示 : 


y Kivy Architecture 


Core providers Graphics Inputs 


Window Vertex Buffer Motion Event 
Text Frame Buffer Post processing 





Image Texture (double tap, 
Video Shader dejitter...) 
Audio Instructions 








核心 模块 和 输入 模块 


对 理解 Kivy 的 设计 内 涵 ， 模 块 化 和 抽象 化 的 思想 是 至 关 重要 的 。 我 们 试图 把 各 种 基本 的 任务 进 
行 抽象 ， 比 如 打开 窗口 、 显 示 图 像 和 文本 、 播 放 音 频 、 从 摄像 头 获 取 图 像 、 拼 写 校 正 等 等 。 
我 们 将 这 些 部 分 称 为 核心 任务 。 这 样 也 使 得 API 接 口 用 起 来 比较 简单 ， 扩 展 起 来 也 容易 。 更 重 
要 的 是 ， 这 种 思路 可 以 让 Kivy 应 用 在 运行 的 时 候 ， 使 用 各 个 运行 平台 所 提供 的 对 应 功能 的 API 
接口 。 例 如 ， 在 苹果 的 MacOS 操 作 系 统 、Linux 操 作 系统 和 Windows 操 作 系统 中 ， 就 都 有 各 自 
不 同 的 原生 API 接 口 提 供 各 种 核心 功能 。 所 以 就 有 一 部 分 代码 ， 调 用 这 些 不 同 接口 中 的 某 一 

个 ， 一 方面 与 操作 系统 进行 通信 ， 另 一 方面 与 Kivy 进 行 交 互 ， 起 到 中 间 人 的 角色 ， 我 们 称 之 为 
核心 模块 。 针 对 不 同 的 操作 系统 平台 要 使 用 各 自 对 应 的 核心 模块 ， 这 样 的 好 处 是 达到 一 种 均 
衡 状 态 ， 既 能 够 充分 利用 操作 系统 提供 的 功能 ， 又 能 尽量 提高 开发 效率 。 ( 译 者 注 : 我 的 理 
解 是 这 样 大 家 平时 不 用 针对 不 同 操作 系统 去 学 习 和 使 用 各 自 的 API， 而 只 要 专心 使 用 Kivy 的 核 
心 模块 进行 调用 就 行 了 。) 这 也 允许 用 户 来 自由 选择 ， 使 用 Kivy 提 供 的 核心 模块 ， 或 者 直接 使 
用 各 个 操作 系统 的 API 接 口 。 此 外 ， 由 于 使 用 了 各 个 平台 所 提供 的 链接 库 文件 ， 我 们 大 大 减 小 
了 Kivy 发 型 版 本 的 体积 ， 也 使 得 打包 发 布 更 加 容易 。 这 有 助 于 将 Kivy 应 用 移植 到 其 他 平台 。 比 
如 Android 平 台 上 的 Kivy 应 用 就 体现 了 这 一 特性 的 好 处 了 。 


在 输入 模块 这 部 分 ， 我 们 也 遵循 了 同样 的 思路 。 输 入 模块 ， 是 一 段 代码 ， 用 于 针对 各 种 输入 
设备 提供 支持 ， 比 如 苹果 公司 的 Trackpad 触 摸 板 ，TUIO 多 点 触摸 设备 ， 或 者 是 鼠标 模拟 器 等 
等 。 如 果 你 需要 对 某 一 种 新 的 输入 设备 添加 支持 ， 只 需要 提供 一 个 新 的 类 ， 用 这 个 类 来 读 取 
输入 设备 的 数据 ， 然 后 传递 给 Kivy 基 本 事件 ， 就 可 以 了 。 


图 形 接 口 


Kivy 的 图 形 接 口 是 对 OpenGL 的 抽象 。 在 最 底层 ，Kivy 使 用 OpenGL 的 命令 来 进行 硬件 加 速 的 
图 形 绘制 。 不 过 写 OpenGL 的 代码 可 还 是 捍 复 杂 的 ， 新 手 就 更 难以 迅速 掌握 了 。 所 以 我 们 就 提 
供 了 一 系列 的 图 形 接口 ， 利 用 这 些 接口 可 以 很 简单 地 进行 图 形 绘制 ， 这 些 接口 中 用 到 了 例如 
画布 Canvas、 拢 形 Rectangle 等 几何 概念 ， 比 OpenGL 里 面 简单 不 少 。 


Kivy 自 带 的 所 有 控件 ， 都 使 用 了 这 个 图 形 接口 ; 出 于 性 能 的 考虑 ， 此 图 形 接口 是 用 C 语 言 来 实 
现 的 。 

这 个 图 形 接口 的 另 一 个 好 处 是 可 以 对 你 代码 中 的 绘图 指令 进行 自动 优化 。 这 个 很 有 用 ， 尤 其 
是 在 你 对 OpenGL 的 优化 不 太 熟悉 的 情况 下 。 这 能 让 你 的 绘图 代码 更 高 效 。 

当然 了 ， 你 也 可 以 坚持 使 用 原生 的 OpenGL 命 令 。 目 前 Kivy 在 所 有 操作 系统 平台 上 用 的 都 是 是 
OpenGL 2.0 ES (GLES2)， 所 以 如 果 你 希望 保持 跨 平 台 的 兼容 性 ， 我 们 建议 你 只 是 用 GLES2 
兼容 的 函数 。 


核心 模块 


核心 模块 也 就 是 kivy.core， 这 个 包 里 面 提 供 了 常用 的 各 种 功能 ， 比 如 : 


Clock 
时 钟 类 ， 可 以 用 于 安排 计时 器 事件 。 同 时 支持 一 次 性 计时 和 周期 性 计时 。 
Cache 


If you need to cache something that you use often, you can use our class for that 
instead of writing your own. 


缓存 类 ， 如 果 有 一 些 经 常用 到 的 数据 需要 缓存 ， 就 可 以 用 这 个 类 ， 而 不 用 自己 写 了 。 
Gesture Detection 


手势 识别 ， 这 个 可 以 用 来 识别 各 种 划 动 行为 ， 比 如 画 个 圆圈 或 者 方块 之 类 的 。 可 以 训练 
来 识别 你 自己 设计 的 图 形 。 


Kivy Language 
Kivy 语 言 ， 这 个 是 用 来 简洁 高 效 地 描述 Kivy 应 用 的 用 户 界面 的 。 
Properties 


这 里 这 些 属性 和 Python 语言 中 的 属性 不 同 。 这 里 是 我 们 专门 写 的 一 些 类 ， 通 过 用 户 界面 
描述 来 连接 控件 代码 。 


UIX (控件 和 布局 ) 


UIX 用 户 界 面 模块 ， 包 含 了 常用 的 各 种 控件 和 布局 ， 可 以 通过 复 用 来 快速 构建 用 户 界面 。 


Widgets 控件 


T ， 可 以 添加 到 程序 中 来 提供 各 种 功能 。 有 的 可 见 ， 有 的 不 可 
。 文 件 浏览 器 ， 按 钮 、 渭 动 页 、 列 表 等 等 ， 这 都 属于 控件 。 控 件 接收 动作 事件 。 


Layouts 布局 


布局 是 控件 的 排列 方式 。 当 然 ， 你 也 可 以 自己 自 定义 控件 的 位 置 ， 不 过 从 我 们 提供 的 预 
设 布局 中 选择 一 个 来 使 用 ， 会 更 方便 很 多 。 网 格 布局 、 箱 式 布局 等 等 ， 都 是 布局 了 。 你 
还 可 以 试 试 复杂 的 多 层 网 状 布局 。 


模块 化 


如 果 你 用 某 一 种 现代 的 网 络 浏览 器 ， 并 且 通 过 一 些 附加 组 件 对 其 进行 定制 ， 那 么 你 应 该 就 理 
解 了 我 们 提供 的 各 种 模块 类 的 基本 思想 了 。 各 种 模块 可 以 用 来 向 Kivy 程 序 中 添加 功能 ， 即 便 原 
作者 没有 提供 的 功能 也 可 以 加 进去 了 。 


例如 ， 有 一 个 模块 就 能 显示 当前 应 用 的 FPS (Frame Per Second > #4) ia > FPP Ae) ， 然 
后 还 能 统计 一 段 时 间 的 FPS 变 化 。 


你 可 以 自己 写 各 种 模块 添加 到 应 用 中 。 


输入 事件 (Touches) 


Kivy 抽 象 了 各 种 输入 类 型 和 输入 设备 ， 比 如 触 控 ， 鼠 标 按 键 ， 多 点 触摸 等 等 。 这 些 输入 类 型 有 
一 个 共同 点 ， 就 是 都 可 以 把 各 种 输入 事件 映射 成 屏幕 上 对 应 的 一 种 2D 形 态 。 (当然 了 ， 还 有 
的 输入 设备 就 没 法 用 2D 形 态 来 表示 ， 比 如 通过 加 速度 传感器 来 衡量 设备 倾斜 角度 等 。 这 种 情 
况 就 得 另外 考虑 了 。 下 面 我 们 讨论 的 只 是 那些 能 用 2D 形 态 表示 的 输入 事件 ， 复 杂 的 类 型 以 后 
再 说 。) 


这 些 输入 类 型 ， 在 Kivy 中 都 用 Touch() 类 的 实例 来 表示 。 (请 注意 ， 这 里 可 不 仅仅 是 针对 手指 
而 是 所 有 可 以 这 样 抽象 表示 的 输入 事件 。 这 里 用 Touch 只 是 为 了 方便 而 
么 简称 一 下 。 就 想象 一 下 ， 这 些 Touches 就 是 在 用 户 界 面 或 者 显示 屏 上 面 的 那些 个 点 击 行 
o ) Touch 的 实例 或 者 对 象 ， 有 三 种 状态 。 当 这 个 Touch 进 入 了 其 中 的 某 一 个 状态 ， 你 的 程 
RS ls 。Touch 的 三 种 状态 如 下 : 


e Down 落下 
处 于 落下 状态 ， 只 能 有 一 次 ， 就 是 在 发 生 Touch 事 件 的 初始 时 刻 。 
e Move 移动 


这 个 状态 的 时 间 无 上 限 。 在 一 个 Touch 的 生命 周期 中 可 以 没有 这 个 状态 。 移 动 状态 只 发 生 
在 Touch 的 2D 平 面 位 置 发 生变 化 的 情况 下 。 


e Up 抬 起 


A touch goes up at most once, or never. In practice you will almost always receive an up 
event because nobody is going to hold a finger on the screen for all eternity, but it is not 
guaranteed. If you know the input sources your users will be using, you will know 
whether or not you can rely on this state being entered. 


一 个 Touch 要 么 只 能 抬 起 一 次 ， 要 么 就 不 发 生 。 而 实际 应 用 中 你 会 经 常 遇 到 Up 时 间 ， 因 


为 没有 人 会 一 直 把 手指 按 到 屏幕 上 ， 不 过 也 有 未 必 就 绝对 不 会 有 这 种 情况 。 若 事先 知道 
用 户 用 的 输入 设备 ， 就 可 以 确定 能 否 完全 依靠 用 户 的 输入 状态 。 


(GEA IE : 以 手指 触摸 屏幕 为 例 ， 只 有 开始 接触 的 时 候 是 Down 手 指 落下 这 个 状态 ， 之 后 
移动 就 是 接 下 来 的 Move 移 动 状态 ， 手 指 抬 起 来 的 时 候 就 是 Up 即 奏 起 状态 了 ; 如 果 以 鼠标 
左 键 点 击 为 例 ， 按 下 去 左 键 的 时 候 是 Down， 按 住 左 键 不 放 进 行 拖 动 就 是 Move， 松 开 左 
键 就 是 Up 了 。 这 段 我 特别 解释 一 下 ， 因 为 自己 翻译 的 太 生 硬 了 。) 


控件 和 事件 调度 


在 图 形 化 的 软件 开发 语 境 下 ， 控 件 这 个 词 经 常 出 现 ， 一 般 是 来 描述 程序 中 用 于 和 用 户 进行 交 
互 的 组 件 。 在 Kivy 中 ， 控 件 是 用 来 接收 各 种 输入 事件 的 。 所 以 并 不 一 定 非 要 在 屏幕 上 能 看 得 
到 。Kivy 当 中 所 有 控件 都 以 控件 树 的 形式 来 管理 ， 学 过 计算 机 科学 中 数据 结构 相关 知识 的 话 
就 会 意识 到 这 是 一 种 树 形 结构 : 一 个 控件 可 以 有 任意 多 个 子 控件 ， 也 可 以 没有 子 控件 。 根 控 
件 就 只 能 有 一 个 ， 处 于 树 形 结构 的 顶端 ， 根 控件 不 具有 父 控 件 ， 并 且 所 有 其 他 控件 都 是 根 控 
件 的 直接 或 者 间接 子 控 件 (就 像 树 根 一 样 ， 所 以 叫 根 控件 ) 。 


» 


当 新 的 输入 数据 可 用 的 时 候 ，Kivy 会 针对 每 一 个 Touch 发 出 一 个 事件 。 控 件 树种 的 根 控件 首先 
接收 到 这 个 事件 。Touch 的 不 同 状态 ，on _ touch. down, on touch_move 和 on_touch_up 

(Down 落 下 、Move 移 动 和 Up) ， 会 作为 Touch 的 参数 ， 提 供给 根 控 件 ， 根 控件 会 调用 对 应 
的 事件 Handler 来 作出 反应 。 


包括 根 控件 在 内 ， 控 件 树种 的 每 个 控件 都 可 以 有 两 种 选择 ， 处 理 该 事件 ， 或 者 将 该 事件 传递 
下 去 。 如 果 一 个 事件 的 Handler 返 回 True， 就 意味 着 这 个 事件 已 经 被 接收 并 妥善 处 理 。 这 个 事 
件 就 也 到 此 为 止 了 。 如 果 不 是 这 样 ， 事 件 的 Handler 会 跳 过 此 处 的 空间 ， 调 用 父 类 中 的 对 应 事 
件 的 Handler 实 现 ， 传 递 给 该 控件 的 子 控件 。 这 样 的 过 程 可 以 一 路 走 到 最 基础 的 控件 类 
Widget， 在 它 的 Touch 事 件 Handler 中 ， 只 是 把 Touch 传 递 给 子 控件 ， 而 不 进行 其 他 的 操作 。 


# This is analogous for move/up: 
def on_touch_down(self, touch): 
for child in self.children[:]: 
if child.dispatch('on touch down', touch): 
return True 
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速 创建 应 用 了 。 


经 常 有 一 种 情况 ， 就 是 你 可 能 要 让 一 个 控件 只 在 屏幕 上 某 个 特定 的 区 域 来 监听 Touch 事 件 。 这 
时 候 就 可 以 使 用 控件 的 collide_point() 方 法 来 实现 此 目的 。 只 需要 把 Touch 的 位 置 发 给 该 方法 ， 
然后 如 果 此 位 置 位 于 监听 区 域 则 返回 True， 反 之 返回 False。 默 认 情 况 下 ， 这 个 方法 会 监听 愤 
幕 上 的 一 个 矩形 区 域 ， 根 据 控件 的 中 心 坐 标 (X& y 坐 标 系 ) ， 以 及 空间 尺寸 (宽度 和 高 

È) ， 不 过 你 也 可 以 用 自己 的 类 和 覆盖 掉 这 一 行为 。 
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Kivy 中 文 编程 指南 : 事件 和 属性 


英文 原文 


译 者 前 言 
这 一 章节 是 我 有 史 以 来 翻译 质量 的 低谷 ， 一 来 是 我 自己 也 是 刚 学 ， 半 懂 不 懂 ， 二 来 本 身 语 言 
基础 各 方面 也 薄弱 ， 三 来 是 笔记 本 坏 掉 了 ， 摘 个 ChromeOS 折 腾 中 。 


大 家 凑合 看 看 ， 看 不 下 去 给 指出 来 一 下 比较 不 好 理解 和 绕 的 地 方 ， 以 及 错误 的 地 方 ， 我 一 定 
即时 修改 。 


简要 介绍 


在 Kivy 开 发 过 程 中 ， 事 件 是 最 重要 的 一 部 分 了 。 如 果 之 前 有 过 GUI 图 形 界面 开发 的 经 验 的 话 ， 
你 可 能 对 此 习以为常 了 ， 但 对 新 手 来 说 ， 这 个 概念 很 重要 。 一 旦 你 理解 了 事件 的 应 用 和 搭 
配 ， 你 就 会 发 现在 Kivy 开 发 的 过 程 中 ， 事 件 是 无 处 不 在 的 。 有 了 各 种 事件 的 搭配 ， 你 就 可 以 用 
Kivy 来 搭建 你 想 要 的 各 种 功能 了 o 


下 面 这 幅 图 展示 了 Kivy 框 架 中 事件 的 处 理 过 程 : 


Kivy's Main Thread 
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事件 分 派 器 


事件 分 派 器 EventDispatcher c 是 Kivy 框 架 中 最 重要 的 基 类 之 一 。 通 过 这 个 类 ， 用 户 可 以 注册 
各 种 事件 ， 然 后 分 发 给 对 应 的 部 件 (一 般 情 况 下 是 其 他 的 事件 分 派 器 ) 。 ER 动画 
类 Animation 以 及 时 间 类 Clock 都 属于 事件 分 派 器 


事件 分 派 器 对 象 要 在 整个 程序 的 循环 流程 的 基础 上 来 生成 和 处 理 各 种 事件 。 


主流 程 


上 文 的 简介 概括 起 来 是 说 ， GR 这 个 循环 体会 在 Kivy 应 用 的 整个 生命 周期 中 
一 直 运 行 ， 直 到 退出 应 用 的 时 候 才 结 


在 循环 内 部 ， 每 一 步 迭 代 都 伴随 有 各 种 事件 生成 ， 这 些 事件 可 以 来 自用 户 输入 、 硬 件 传 感 
器 ， 或 者 是 其 他 的 各 种 来 源 ， 然 后 一 帧 一 帧 地 浑 染 到 屏幕 上 。 


你 写 的 应 用 程序 将 要 指定 好 各 种 由 主 循环 进行 调用 而 产生 的 回调 〈callback， 稍 后 再 详细 介绍 
相关 内 容 ) 。 如 果 一 次 回调 花费 很 长 时 间或 者 根本 不 退出 ， 主 循环 就 被 打破 了 ， 你 的 应 用 也 
就 不 能 正常 工作 了 。 


在 Kivy 应 用 里 面 ， 一 定 要 避免 用 特别 长 的 循环 、 无 限 循 环 ， 或 者 休眠 。 下 面 这 个 代码 就 同时 是 
死 循环 + 休眠 ， 就 是 一 个 反例 了 


while True: 
animate something() 
time.sleep(.10) 


如 果 把 上 面 这 段 代 码 拿 去 运行 ， 那 程序 就 会 无 法 退出 循环 了 ， 就 让 Kivy 卡 住 了 ， 什 么 后 续 步 又 
都 不 能 进行 了 。 用 户 就 只 能 看 到 一 个 黑色 的 窗口 ， 什 么 操作 都 没有 响应 。 不 能 死 循环 也 不 能 
休眠 ， 所 以 就 得 想 其 他 办 法 ， 比 如 有 计划 地 重复 调用 对 animate_something() 这 样 的 函数 。 

(animate_something 的 意思 是 让 某 个 东西 动 起 来 ， 作 者 是 用 来 指 代 类 似 的 这 种 需要 时 不 时 
重复 调用 的 函数 。) 


计划 周期 事件 


利用 schedule_interval() 这 个 函数 ， 你 就 可 以 每 秒 对 某 个 函数 或 者 方法 进行 指定 次 数 的 调用 
了 。 下 面 就 是 一 个 例子 ， 在 这 段 代码 的 第 三 行 ， 实 现 了 每 秒 钟 调用 my_callback(dt) 函 数 三 十 


次 : 


def my_callback(dt): 
print 'My callback is called', dt 
event = Clock.schedule pipette callback, 1 / 30.) 
# 译 者 I1/30 明 显 就 是 频率 的 倒数 了 ， 如 果 是 每 秒 钟 50 次 就 应 该 是 /50， 以 此 类 推 了 ， 大 家 可 以 自己 修改 试 





要 取消 之 前 的 计划 事件 有 多 种 方法 。 可 以 用 cancel()， 也 可 以 用 unschedule() : 


event .cancel() 


# 或 者 用 下 面 这 种 方法 


Clock.unschedule(event) 


再 有 一 种 方法 ， 就 是 在 回调 的 时 候 返 回 False， 这 样 这 个 事件 就 会 被 自动 取消 计划 ， 不 再 重 
A1 


count - 0 
def my callback(dt): 
global count 
count += 1 
if count == 10: 
print 'Last call of my callback, bye bye !' 
return False 
print 'My callback is called' 
Clock.schedule interval(my callback, 1 / 30.) 


计划 一 次 性 事件 


使 用 schedule_once() 辑 数 ， 可 以 对 一 个 函数 稍 后 调用 的 效果 ， 可 以 是 在 下 一 帧 ， 也 可 以 是 在 
间 定 时 间 X 之 后 : 


def my_callback(dt): 
print 'My callback is called !' 
Clock.schedule_once(my_callback, 1) 


上 面 这 段 代码 会 在 一 秒 钟 后 再 对 my_callback(dt) 进 行 调 用 。schedule_once() 函 数 的 第 二 个 变 
量 X 就 是 延迟 调用 的 时 间 ， 以 秒 为 单位 。 具 体 这 个 变量 的 用 法 有 以 下 三 种 : 


e 若 X 大 于 零 ， 则 作为 时 间 长 度 的 秒 数 ， 延 迟 X 秒 之 后 进行 下 一 次 调用 
e 若 X 等 于 零 ， 则 在 下 一 帧 进行 调用 
e 若 X 为 -1， 调 用 则 发 生 在 下 一 帧 泻 染 之 前 


假如 你 已 经 有 了 一 个 计划 事件 ， 但 又 想 要 在 下 一 帧 泻 染 之 前 计划 一 次 调用 ， 这 种 情况 就 适合 
使 用 -1 这 种 用 法 。 


这 里 就 有 了 一 种 衍生 出 来 的 重复 调用 某 个 函数 的 方法 ， 就 是 在 函数 体内 放 一 个 
schedule_once()， 然 后 在 第 二 次 调用 该 函数 的 时 候 ， 函 数 内 的 schedule_once() 就 会 继续 对 本 
身 进行 调用 了 : 


def my_callback(dt): 
print 'My callback is called !' 
Clock.schedule_once(my_callback, 1) 
Clock.schedule_once(my_callback, 1) 


主 循环 会 一 直 按照 代码 的 要 求 来 保持 各 种 计划 调用 的 实现 ， 但 一 次 计划 调用 发 生 的 具体 时 间 
OA 
久 一 些 ， 这 时 候 用 计时 的 方法 制定 计划 就 不 太 合适 了 。 


后 面 介绍 的 这 种 用 内 置 schedule_once() 来 进行 重复 回调 问题 的 解决 方案 中 ， 在 最 后 一 次 迭代 
结束 后 ， 下 一 次 迭代 将 至 少 要 一 秒 之 后 才能 被 调用 。 而 使 用 schedule_interval() 这 种 方法 就 可 
以 每 秒 都 进行 回调 。 


触发 事件 


Salonen 人 函数 只 需要 计划 在 下 一 帧 调用 一 次 ， 而 不 允许 重复 调用 。 这 时 候 就 可 以 用 下 
这 样 的 思路 来 实现 : 


# 首 先是 用 Schedule_once( ) 计 划 调 用 一 
event = Clock.schedule_once(my_callback, 0) 


# 然 后 在 另外 一 个 位 置 ， 就 用 unschedule( ) 取 消 计划 调用 ， 这 样 就 能 避免 重复 调用 。 接 下 来 就 是 再 次 用 schedule_o 
nce( ) 进 行 计划 调用 

Clock.unschedule(event) 

event = Clock.schedule_once(my_callback, 0) 





面 这 种 方法 构建 触发 器 可 谓 费 时 费力 ， 因 为 你 得 经 常用 到 unschedule， 即 使 一 个 事件 已 经 
结束 。 此 外 ， 每 次 还 都 产生 新 事件 。 所 以 可 以 用 下 面 这 个 trigger() 来 作为 触发 器 : 


trigger = Clock.create trigger(my callback) 
4 later 
trigger() 


这 样 你 每 次 调用 trigger() 就 可 以 了 ， 这 个 触发 器 会 对 你 的 my_callback 回 调 进行 单 次 计划 调 
用 。 如 果 之 前 存在 计划 调用 了 ， 则 不 重新 产生 计划 调用 。 


控件 事件 

控件 有 两 种 默认 事件 : 

e 属性 事件 : 比如 你 的 控件 改变 了 位 置 或 者 大 小 ， 就 会 触发 一 个 事件 。 

e 控件 定义 的 事件 : 比如 一 个 Button 按 钮 控件 被 按 下 或 者 松 开 ， 也 会 触发 一 个 事件 。 


关于 控件 的 Touch 事 件 的 管理 和 传播 ， 可 以 参考 AP|I 文 档 中 这 部 分 相关 内 容 。 


创建 自 定义 事件 


要 使 用 自 定义 事件 创建 事件 分 派 器 ， 需 要 首先 在 类 中 注册 事件 名 称 ， 然 后 创建 同名 的 方法 。 


例如 下 面 这 段 代码 所 示 : 


class MyEventDispatcher(EventDispatcher): 
def X init (self, **kwargs): 
self.register event type('on test') 
super(MyEventDispatcher, self). init (**kwargs) 


def do something(self, value): 
# when do something is called, the 'on test' event will be 
# dispatched with the value 
self.dispatch('on test', value) 


def on test(self, *args): 
print "I am dispatched", args 


附加 回调 


要 利用 一 个 事件 ， 必 须要 对 其 绑 定 回调 。 当 事件 被 分 派 的 时 候 ， 该 特定 事件 相关 的 参数 将 被 
用 于 调用 回调 。 


回调 可 以 使 Python 中 能 进行 调用 的 任意 内 容 ， 函 数 或 者 方法 都 可 以 ， 但 一 定 要 确保 回调 要 接 
收 事件 发 出 的 参数 。 最 安全 的 常规 做 法 是 接收 * args 参 数 ， 将 所 有 参数 都 存放 成 一 个 参数 列 
表 o 


例如 : 


def my_callback(value, *args): 
print "Hello, I got an event!", args 


ev = MyEventDispatcher() 


ev.bind(on test-my callback) 
ev.do something('test') 


请 阅读 参考 kivy.event.EventDispatcher.bind() 方法 的 文档 来 查看 更 多 附加 调用 相关 的 样 例 。 


简介 属性 Properties 


TRA 十 月 的 天 空 提示 : attribute 和 property 都 翻译 成 了 属性 ， 字 面 上 确实 没 错 ， 但 是 读 
起 来 就 英名 其 妙 了 。 从 本 质 上 讲 property 是 kivy 特色 ， 个 人 理解 property 包含 于 
attitude 而 且 绑 定 widget 类 ， 是 否 可 以 翻译 成 控件 属性 或 者 构件 属性 之 类 。 


& 


控件 属性 (Properties) 是 定义 和 绑 定 事件 的 一 种 很 赞 的 办 法 。 关 键 就 是 属性 能 生成 事件 ，:; 
样 当 你 的 某 个 对 象 中 有 一 个 属性 (attribute) 发 生 改 变 的 时 候 ， 所 有 引用 该 属性 (attribute ) 
的 控件 属性 (Properties) 都 会 被 自动 更 新 
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针对 你 要 处 理 的 数据 类 型 ， 存 在 很 多 种 不 同类 型 的 控件 属性 dt (Properties) 


e 字符 串 属 性 StringProperty 

e 数值 属性 NumericProperty 

e 有 界 数值 属性 BoundedNumericProperty 
e 对 象 属性 ObjectProperty 

e 词典 属性 DictProperty 

e 列表 属性 ListProperty 

e 选项 属 ， 
e 别名 属 ' 
e 布尔 属 ， 
e 引用 属 ， 


E a. as 


+ OptionProperty 


—= 


* AliasProperty 


——r 


* BooleanProperty 


i 


+ ReferenceListProperty 


+ 
属性 声明 

要 声明 控件 属性 (Properties) ， 必 须要 在 类 的 层次 上 进行 声明 。 接 下 来 这 个 类 才能 在 你 创建 
pO DE ESTE (attributes) 进行 实例 化 。 此 控件 属性 (Properties) 非 彼 属性 


(attributes) > 控件 属性 Properties 是 根据 你 的 attributes 来 创建 事件 的 机 制 ， 例 如 : 


class MyWidget(Widget): 
text = StringProperty('') 
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的 初始 化 方法 init， 传 递 自 定义 类 的 实例 过 去 : 


def init__(self, **kwargs): 
super(MyWidget, self). init (**kwargs) 


分 派 属性 事件 


Kivy 的 控件 属性 Property， 默 认 提 供 了 一 个 on_ 事件 。 在 属性 被 改变 的 时 候 ， 就 会 调用 这 个 事 
件 了 。 


特别 注意 


如 果 属 性 的 新 值 与 当前 已 有 的 值 相 等 ， 那 么 on_ 事件 就 不 会 被 调用 了 。 


例如 下 面 这 段 代码 : 


class CustomBtn(Widget): 
pressed = ListProperty([0, 0]) 
def on_touch_down(self, touch): 
if self.collide_point(*touch.pos): 
self.pressed = touch.pos 
return True 
return super(CustomBtn, self) .on_touch_down( touch) 
def on_pressed(self, instance, pos): 


print ('pressed at {pos}'.format(pos=pos) ) 


上 面 代码 的 第 三 行 中 : 


pressed = ListProperty([0, 0]) 


这 一 名 中 ， 基 于 ListProperty 定 义 了 一 个 pressed 按 下 的 属性 ， 黑 认 值 是 [0,0]。 从 这 往 后 ， 只 要 
这 个 属性 被 改变 了 ，on_presses 事 件 就 会 被 调用 。 


第 五 行 有 如 下 代码 : 


def on_touch_down(self, touch): 
if self.collide_point(*touch.pos): 
self.pressed = touch.pos 
return True 
return super(CustomBtn, self) .on_touch_down( touch) 


这 部 分 代码 覆盖 了 控件 类 的 _touch_down() 方 法 。 这 段 代码 中 ， 用 控件 对 touch 触 碰 的 位 置 进 
行 了 检测 。 


如 果 touch 的 位 置 在 控件 范围 内 ， 就 把 pressed 的 值 改变 成 touch.pos 这 个 值 ， 然 后 返回 True * 
这 表明 程序 已 经 处 理 好 了 这 个 touch 了 ， 就 把 这 个 touch 消 耗 掉 了 ， 不 用 再 传播 了 。 


如 果 touch 的 位 置 在 控件 外 部 ， 就 通过 super(...) 了 调用 原始 事件 ， 并 返回 结果 。 这 就 和 常规 情 
况 一 样 了 ，touch 事 件 会 被 继续 传递 下 去 。 


在 第 十 一 行 : 


def on_pressed(self, instance, pos): 
print ('pressed at {pos}'.format(pos=pos) ) 


这 里 定义 了 一 个 on_pressed 了 有 函数， 只 要 属性 值 发 生 改 变 了 ， 这 个 函数 就 会 被 调用 。 


特别 注意 
这 个 on_ 事件 是 在 类 内 定义 属性 的 位 置 被 调用 。 在 定义 该 属性 的 类 之 外 ， 若 要 监控 /观察 一 个 
属性 的 任何 变动 ， 就 必须 丢 这 个 属性 进行 bind 绑 定 操作 。 


只 能 读 取 到 一 个 控件 实例 的 时 候 ， 要 怎么 去 监控 属性 的 变化 呢 ? 这 时 候 用 bind 绑 定 一 下 属性 


your widget instance.bind(property name-function name) 


例如 下 面 这 段 代码 : 


class RootWidget(BoxLayout): 


def init__(self, **kwargs): 
super(RootWidget, self). init (**kwargs) 
self.add widget(Button(text-'btn 1')) 
cb = CustomBtn() 
cb.bind(pressed-self.btn pressed) 
self.add widget(cb) 
self.add widget(Button(text-'btn 2')) 


def btn pressed(self, instance, pos): 
print ('pos: printed from root widget: {pos}'.format(pos=.pos) ) 


如 果 运 行 上 面 这 段 代码 ， 会 发 现 有 两 次 print 输 出 语句 出 现在 控制 台中 。 第 一 个 是 来 自 
_pressed 事 件 ， 在 CustomBtn 类 内 部 调用 ; 另外 一 次 print 是 来 自我 们 用 bind 绑 定 到 了 属性 变化 
+ #Jbtn_pressed i X » 


( 译 者 注 : 在 用 bind 绑 定 了 之 后 ， 属 性 的 变化 都 会 通过 bind 的 函数 被 看 到 了 。 ) 


两 个 函数 都 被 调用 的 原因 很 简单 。Bind 绑 定 操作 并 不 意味 着 履 盖 。 这 两 个 函数 同时 保留 就 兄 
余 了 ， 所 以 一 般 情况 你 只 选择 一 个 来 对 属性 变化 进行 监听 /反应 就 行 了 。 


你 还 得 注意 一 下 传递 给 on_ 事 件 或 者 绑 定 到 属性 的 函数 的 参数 。 
def btn_pressed(self, instance, pos): 


Aj 


第 一 个 参数 是 self， 这 就 是 该 函数 所 在 类 本 身 的 一 个 实例 。 也 可 以 用 内 联 函 数 ， 如 下 代码 所 
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cb = CustomBtn() 


def _local_func(instance, pos): 
print ('pos: printed from root widget: {pos}'.format(pos=pos) ) 


cb.bind(pressed- local func) 
self.add widget(cb) 


第 一 个 参数 是 定义 属性 的 类 的 实例 。 第 二 个 参数 是 一 个 值 ， 这 个 值 是 属性 的 新 值 。 上面 那 一 
段 只 是 代码 片段 ， 下 面 这 一 段 代码 是 完整 的 样 例 了 ， 可 以 复制 粘贴 到 编辑 器 里 面 然 后 测试 一 


from 
from 
from 
from 
from 


clas 


clas 


clas 


if 


kivy.app import App 

kivy.uix.widget import Widget 
kivy.uix.button import Button 
kivy.uix.boxlayout import BoxLayout 
kivy.properties import ListProperty 


s RootWidget(BoxLayout): 


def _ init (self, **kwargs): 
super(RootWidget, self). init (**kwargs) 
self.add widget(Button(text-'btn 1')) 
cb = CustomBtn() 
cb.bind(pressed-self.btn pressed) 
self.add widget(cb) 
self.add widget(Button(text-'btn 2')) 


def btn pressed(self, instance, pos): 
print ('pos: printed from root widget: {pos}'.format(pos=pos) ) 


s CustomBtn(Widget): 


pressed = ListProperty([0, 0]) 


def on_touch_down(self, touch): 
if self.collide_point(*touch.pos): 
self.pressed = touch.pos 
# we consumed the touch. return False here to propagate 
# the touch further to the children. 
return True 
return super(CustomBtn, self).on_touch_down(touch) 


def on_pressed(self, instance, pos): 
print ('pressed at {pos}'.format(pos=pos) ) 


s TestApp(App): 


def build(self): 
return RootWidget() 


name — made: 
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TestApp().run() 


了 上面 这 段 完 整 的 样 例 代 码 ， 会 得 到 如 下 图 所 示 的 输出 : 





咱们 这 个 CustomBtn 没 有 做 任何 视觉 上 的 调整 ， 所 以 就 是 个 大 黑 块 。 你 可 以 触摸 /点 击 这 个 黑 
色 的 区 域 ， 来 看 看 控制 台 里 面 的 输出 。 


复合 属性 


定义 一 个 别名 属 ， bd a 时 候 ， 通 常 要 定义 一 个 getter 函 数 和 一 个 setter 函 数 ， 前 者 
用 来 读 取 值 ， 后 者 用 来 设 定 值 。 这 时 候 ， 你 就 得 通过 bind 绑 定 参数 来 确定 好 getter 和 setter 元 
数 的 调用 时 间 。 


例如 下 面 这 段 代码 : 


cursor_pos = AliasProperty(_get_cursor_pos, None, bind=( 
"cursor , “padding”, ‘pos’, saze “focus, 
SGIOlI SOO yy 

i Cusgent position of ther Curgsorm, n(x ye 


:attr: cursor pos! is a :class: ~kivy.properties.AliasProperty , read-only. 


densi 


这 里 的 cursor_pos (光标 位 置 的 意思 ) 就 是 一 个 别名 属性 AliasProperty， 它 有 一 个 getter 声 
数 ， 名 为 get_cursor_pos()， 然 后 没有 设置 setter 函 数 ， 这 就 说 明 这 个 属性 是 只 读 的 。 


最 末尾 那 一 段 的 bind 参 数 的 意思 是 ， 当 在 bind= 这 个 等 号 后 括号 内 的 属性 中 有 任意 的 一 个 发 生 
变化 ， 都 会 分 派 on_cursor pos 事件 。 


Title: Kivy Input management Date: 2017-02-12 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 输入 管 ; 


译 者 前 言 


这 一 章节 上 比 上 一 章节 翻译 的 还 差 ， 最 近 睡 眠 不 太 好 ， 术 后 恢复 比较 差 ， 大 家 凑合 看 看 ， 看 不 
去 给 指出 来 一 下 比较 不 好 理解 和 绕 的 地 方 ， 以 及 错误 的 地 方 ， 我 一 定 即 时 修改 。 


输入 体系 


Kivy 能 处 理 绝 大 多 数 的 输入 类 型 : 鼠标 ， 和 触摸 屏 ， 加 速 器 ， 陀 螺 仪 等 等 。 并 且 针 对 以 下 平台 能 
够 处 理 多 点 触 控 的 原生 协议 : Tuio, WM Touch, MacMultitouchSupport, MT Protocol A/B 以 
及 Android » ( 译 者 注 : 第 一 个 TUIO 应 该 是 通用 多 点 触 控 ， 第 二 个 怀疑 是 WindowsMobile 
的 ， 第 三 个 是 革 果 的 多 点 触 控 ， 第 四 个 不 知道 是 啥 ， 最 后 一 个 是 Android 的 。) 


整体 上 输入 体系 的 结构 概括 起 来 如 下 所 示 : 


Input providers -> Motion event -> Post processing -> Dispatch to Window 


输入 源 -> 动作 事件 -> 事后 处 理 -> 分 派 到 窗口 


所 有 输入 事件 的 类 是 MotionEvent 。 这 个 类 生成 两 种 事件 : 


e Touch 触 控 事 件 : 包含 位 置信 息 ， 至 少 X 和 Y 坐 标 位 置 的 一 种 Motion 动 作 事件 。 所 有 这 
Touch 事 件 都 通过 控件 树 进 行 分 派 


e pus iip A : 其 余 的 各 种 事件 。 例 度 传感器 就 是 一 个 持续 的 事件 ， 不 有 具 
有 坐标 位 置 。 这 一 事件 没有 起 止 ， 一 直 在 发 生 。 这 类 的 事件 都 不 通过 控件 树 来 分 派 。 


MA InputProvider 生成 的 。 InputProvider 这 个 类 就 是 负责 读 取 输 入 事件 ， 
这 些 输入 事件 的 来 源 可 以 是 操作 系统 ， 网 络 或 者 其 他 的 应 用 程序 。 如 下 这 几 个 都 是 已 有 的 输 
入 源 : 


e TuioMotionEventProvider : 创建 一 个 UDP 服务 端 ， 侦 听 TUIO/OSC 信 息 。 

© WM MotionEventProvider : 使 用 Windows API 来 读 取 多 点 触 控 信息 并 发 送 给 Kivy。 

*  ProbeSysfsHardwareProbe . : Æ Linux ? ， 遍历 连 接 到 计算 机 的 所 有 硬件 2 并 为 找到 的 每 个 
多 点 触摸 设备 附加 一 个 多 点 触摸 输入 提供 程序 。 


e 还 有 很 多 很 多 啦 ! 


当 你 写 一 个 应 用 程序 的 时 候 ， 就 不 用 再 去 重 造 一 个 输入 源 了 。Kivy 会 自动 检测 可 用 的 硬件 。 然 
而 ， 如 果 你 想 要 支持 菜 些 特殊 定制 的 专门 硬件 ， 就 可 能 得 对 Kivy 的 配置 进行 一 下 调整 才 行 。 


在 新 建 的 Motion 动 作 事 件 被 传递 给 用 户 之 前 ，Kivy 会 先 对 输入 进行 处 理 。Kivy 会 对 每 一 个 动作 
事件 进行 分 析 来 检查 和 纠正 错误 输入 ， 也 是 保证 能 提供 有 意义 的 解释 ， 比 如 : 


e 根据 姿势 和 持续 时 间 来 检测 双击 或 三 次 点 击 ; 

e 在 硬件 设备 精度 不 佳 的 情况 下 提高 事件 精确 度 ; 

o 原生 触摸 硬件 若 在 近似 相同 位 置 发 送 事 件 则 降低 生成 事件 数量 。 
经 过 上 面 这 些 步骤 之 后 ， 这 个 Motion 动 作 事件 就 会 被 分 派 给 对 应 的 窗口 。 正 如 之 前 解释 过 
的 ， 并 非 所 有 事件 都 分 派 给 整个 控件 树 ， 程 序 窗 口 要 对 事件 进行 过 滤 筛选 。 对 于 一 个 给 定 的 
事件 : 

. 如 果 仅 仅 是 一 个 Motion 动 作 事件 ， 那 它 就 会 被 分 派 给 on motion() >; 

。 如 果 是 一 个 Touch 事 件 ， 这 个 触摸 控件 的 坐标 位 置 (xy) (范围 在 0-1) 会 被 调整 到 与 窗口 

尺寸 ( 宽 高 ) 相 适 应 ， 然 后 对 应 发 给 下 面 这 些 方法 : 
© on touch down() 


© on touch move() 


O on touch up() 


Meotion 动 作 事件 的 属性 


你 用 的 硬件 和 输入 源 可 能 允许 你 能 获取 到 更 多 信息 。 比 如 一 个 Touch 触 摸 输入 不 仅 有 坐标 位 置 


(xy) ， 还 可 能 有 压力 强度 信息 ， 和 触摸 范围 大 小 ， 加 速度 矢量 等 等 。 


在 Motion 动 作 事件 中 ， 有 一 个 字符 串 作 为 profile 属 性 ， 用 于 说 明 该 事件 内 都 有 那些 可 用 的 效 
果 。 假 如 咱们 有 下 面 这 样 的 一 个 on touch move 方法 : 


def on_touch_move(self, touch): 
print(touch. profile) 
return super(..., self) .on_touch_move( touch) 


在 控制 台 的 打印 输出 可 能 是 : 


['pos', 'angle'] 


特别 注意 


很 多 人 可 能 会 把 这 里 Motion 事 件 的 Profile 属 性 的 名 字 与 对 应 的 Property 属 性 型 混 。 一 定 要 注 
意 ， 可 用 Profile 属 性 中 存在 angle ， 并 不 意味 着 Touch 事 件 对 象 也 必须 有 一 个 angle 的 
Property 属 性 。 


对 应 profile 属 性 'pos' ，property 属 性 中 有 位 置信 息 pos * x,y »profile/& angle ， 
property 属 性 对 应 的 是 有 角度 a 。 刚 刚 我 们 就 说 了 ， 对 touchTouch 事 件 来 说 ，profile 属 性 中 按 
照 惯例 是 必须 有 位 置 属性 pos 的 ， 但 不 一 定 有 角度 属性 angle 。 对 角度 属性 angle EA 

在 ， 可 以 用 下 面 的 方法 来 检测 一 下 : 


def on_touch_move(self, touch): 
print('The touch is at position', touch.pos) 
if 'angle' in touch.profile: 
print('The touch angle is', touch.a) 


在 motionevent 文档 中 ， 可 以 找到 所 有 可 用 profile 属 性 的 列表 。 


Touch 事 件 


有 一 种 特殊 的 MotionEvent 动作 事件 ， 这 种 事件 的 is touch 方法 返回 的 是 True， 这 就 是 
Touch 事 件 。 
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所 有 的 Touch 事 件 ， 都 默认 就 有 X 和 Y 的 坐标 信息 ， 与 窗口 的 宽度 和 高 度 相 匹配 。 换 名 话说 就 
是 所 有 的 Touch 事 件 都 有 pos 这 一 profile 属 性 。 


S 


基本 简介 


默认 情况 下 ，Touch 事 件 会 被 分 派 给 所 有 当前 显示 的 控件 。 也 就 是 说 无 论 这 个 Touch 是 否 发 生 
在 控件 的 物理 范围 内 ， 控 件 都 会 收 到 它 。 


如 果 你 接触 过 其 他 的 GUI 框架 ， 可 能 觉得 这 特点 挺 违背 直觉 的 。 一 般 的 GUI 框架 里 面 ， 都 是 把 
屏幕 分 割 成 多 个 几何 区 域 ， 然 后 只 在 发 生 区 域内 的 控件 才 会 被 分 派 到 触摸 或 者 鼠标 事件 。 


这 个 设 定 对 触摸 输入 的 情景 来 说 就 过 于 严格 了 。 因 为 用 手指 划 ， 之 间 点 戳 ， 还 有 长 时 间 按 ， 
都 可 能 会 有 偏 移 导 致 落 到 用 户 希 望 进行 交互 的 控件 外 的 情景 。 


为 了 提供 最 大 的 灵活 性 ，Kivy 会 把 事件 分 派 给 所 有 控件 ， 然 后 让 控件 来 自行 决定 如 何 应 对 这 些 
事件 。 如 果 你 只 希望 在 某 个 控件 内 对 Touch 事 件 作 出 反应 ， 只 需要 按照 如 下 方法 进行 一 下 检 
M] : 


def on_touch_down(self, touch): 
if self.collide_point(*touch.pos): 
# The touch has occurred inside the widgets area. Do stuff! 
pass 


坐标 位 置 


一 旦 你 使 用 一 个 带 有 矩阵 变换 的 控件 ， 就 一 定 要 处 理 好 Touch 事 件 中 的 和 矩阵 变换 。 例 
如 scatter 这 样 的 某 些 控件 ， 自 身 会 有 短 阵 变换 ， 这 就 意味 着 Touch 事 件 也 必须 用 Scatter 珑 阵 
井 行 处 理 ， 这 样 才能 正确 地 把 Touch 事 件 的 位 置 分 派 给 Scatter 的 子 控件 。 


e 从 上 层 空 间 到 本 地 空间 获取 坐标 : to_local() 

e 从 本 地 空间 到 上 层 空 间 获 取 坐 标 : to parent() 
e 从 本 地 空间 到 窗口 空间 获取 坐标 : to window() 
e 从 窗口 空间 到 本 地 空间 获取 坐标 : to widget() 


一 定 要 使 用 上 面 方 法 当中 的 某 一 种 来 确保 内 容 坐 标 系 适 配 正确 。 然 后 下 面 这 段 代码 里 是 
Scatter 的 实现 : 


def on_touch_down(self, touch): 
# push the current coordinate, to be able to restore it later 
# 这 里 用 push 先 把 当前 的 坐标 位 置 存留 起 来 ， 以 后 就 还 可 以 恢复 到 这 个 坐标 
touch.push() 


# transform the touch coordinate to local space 
接 下 来 就 是 把 Touch 的 坐标 转换 成 本 地 空间 的 坐标 
touch.apply_transform_2d(self.to_local) 


# dispatch the touch as usual to children 

# the coordinate in the touch is now in local space 
H 转换 之 后 把 这 个 Touch 事 件 按照 惯例 分 派 给 予 控件 
# Touch 事 件 的 坐标 位 置 现在 


是 本 地 空间 的 了 
ret = super(..., self).on touch down(touch) 






4 whatever the result, don't forget to pop your transformation 
# after the call, so the coordinate will be back in parent space 
# 无 论 结果 如 何 ， 一 定 记 得 把 这 个 转换 用 pop 弹 出 

# 之 后 ， 坐 标 就 又 恢复 成 上 层 室 间 的 了 

touch.pop() 





# return the result (depending what you want.) 
# 最 后 就 是 返回 结果 了 


return ret 


Touch 3 #4 89 7E AR 
If the touch has a shape, it will be reflected in the ‘shape’ property. Right now, only a 


ShapeRect Can be exposed: 


如 果 你 的 Touch 事 件 有 某 个 形状 ， 这 个 信息 会 反映 在 shape 这 一 property 属 性 中 。 目 前 能 用 的 


就 是 一 个 ShapeRect 


from kivy.input.shape import ShapeRect 
def on_touch_move(self, touch): 
if isinstance(touch.shape, ShapeRect): 
print('My touch have a rectangle shape of size', 
(touch.shape.width, touch.shape.height ) ) 


双击 


A double tap is the action of tapping twice within a time and a distance. It’s calculated by the 
doubletap post-processing module. You can test if the current touch is one of a double tap or 
not: 


i E — AP NTE > E BONS TRU ARA 8 — a E A Aa o MENT HR Sl 
是 通过 一 个 双击 后 处 理 模块 来 实现 的 。 可 以 用 如 下 代码 来 检测 当前 的 Touch 是 否 是 双击 动作 中 
的 一 下 : 


def on_touch_down(self, touch): 
if touch.is_double_tap: 
print('Touch is a double tap !') 
print(' - interval is', touch.double tap time) 
print(' - distance between previous is', touch.double tap distance) 


A triple tap is the action of tapping thrice within a time and a distance. It's calculated by the 
tripletap post-processing module. You can test if the current touch is one of a triple tap or 
not: 


三 次 点 击 和 双击 的 概念 类 似 ， 只 不 过 是 变 成 了 点 击 三 次 。 这 个 是 通过 一 个 三 次 点 击 后 处 理 模 
块 来 计算 识别 的 。 可 以 用 如 下 代码 来 检测 当前 的 Touch 是 否 是 三 次 点 击 动作 中 的 一 下 : 


def on_touch_down(self, touch): 
if touch.is_triple_tap: 
print('Touch is a triple tap !') 
print(' - interval is', touch.triple tap time) 
print(' - distance between previous is', touch.triple tap distance) 


拖 放 事件 


父 控 件 可 能 会 从 on touch down 中 分 派 Touch 事 件 到 子 控件 ， 而 不 
从 on touch move 或 on_touch_up 分 派 。 这 可 能 发 生 在 某 aes 睛 况 知 悉 啊 ， 比 如 一 个 Touch 
处 于 父 控 件 的 边界 之 外 ， 父 控 件 就 会 决定 不 对 子 控件 通知 这 个 Touch 。 


But you might want to do something in on_touch_up . Say you started something in the 
on touch down event, like playing a sound, and you'd like to finish things on the 
on touch up event. Grabbing is what you need. 


不 过 有 可 能 你 还 是 得 处 理 一 下 on touch up 。 比 方 说 ， 你 开始 是 on touch down 事件 ， 假 设 是 
按 下 播放 语音 之 类 的 ， 然 后 你 希望 当 手 指 抬 起 的 时 候 on touch up 事件 发 生 的 时 候 就 结束 任 
务 。 这 时 候 就 需要 有 Grab 拖 放 事 件 了 。 


When you grab a touch, you will always receive the move and up event. But there are some 
limitations to grabbing: 


4&3 — ^ Touch #4) MR > iS AK 81 4$ 25 de d6 ke ETE o (ARIMA de FIR Al : 


e 至 少 会 两 次 收 到 这 个 事件 : 一 次 是 从 父 控 件 正 常 收 到 的 事件 ， 还 有 一 次 是 从 窗口 获取 的 
Grab 拖 放 事 件 。 


e 有 可 能 你 没有 进行 拖 放 ， 但 还 是 会 收 到 一 个 拖 放 Touch 事 件 : 这 可 能 是 因为 在 子 控件 处 于 
， 父 控件 发 来 了 一 个 Touch 事 件 。 


© 在 拖 放 状态 下 ，Touch 事 件 的 坐标 不 会 转换 成 控件 空间 的 坐标 ， 因 为 这 个 Touch 事 件 是 
接 来 自 窗口 的 。 所 以 要 手动 将 坐标 转换 到 本 地 空间 。 


下 面 这 段 代码 展示 了 对 拖 放 的 使 用 : 


Ay 人 E yg 


4 
ENS 


def on_touch_down(self, touch): 
if self.collide_point(*touch.pos): 


# if the touch collides with our widget, let's grab it 
touch. grab(self ) 


# and accept the touch. 
return True 


def on_touch_up(self, touch): 
# here, you don't check if the touch collides or things like that. 
# you just need to check if it's a grabbed touch event 
if touch.grab_current is self: 


# ok, the current touch is dispatched for us. 
# do something interesting here 


print('Hello world!') 


# don't forget to ungrab ourself, or you might have side effects 
touch.ungrab(self) 


4 and accept the last up 
return Thue 


Touch = 4t E 3€ 


想 要 了 解 更 多 Touch 事 件 如 何 控制 以 及 如 何在 控件 之 间 传 递 ， 可 以 阅读 一 下 Widget touch 
event bubbling 这 部 分 内 容 。 
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Title: Kivy Widgets Date: 2017-02-26 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 控件 


英文 原文 
控件 简介 


iii- — 是 Kivy 图 形 界 面 中 的 基本 元 素 。 控 件 提 供 了 一 个 画布 canvas ， 这 是 用 来 在 屏幕 
绘制 的 。 控 件 接收 事件 ， 并 且 对 事件 作出 反应 。 想 要 对 控件 widget 进行 更 深入 的 了 
"i a 个 模块 的 文档 。 


操作 控件 树 


Kivy 以 树 的 形式 来 组 织 控件 。 你 的 应 用 程序 会 有 一 个 根 控件 ， 通 常会 含有 若干 的 子 控件 
children ， 这 些 子 控件 还 可 以 有 自己 的 子 控 件 。 一 个 控件 的 子 控件 会 以 children 属性 的 形 
式 表述 ， 这 个 属性 是 Kivy 中 的 一 个 列表 属性 ListProperty 


可 以 用 一 下 方法 来 操作 控件 树 : 


e add widget() : 添加 一 个 控件 作为 子 控件 ; 
* remove widget() : 从 子 控件 列表 中 去 掉 一 个 控件 ; 
e clear_widgets() :清空 一 个 控件 的 所 有 子 控件 。 


例如 下 面 的 代码 ， 就 是 在 一 个 盒 式 布 局 BoxLayout 中 添加 一 个 按钮 : 


layout = BoxLayout(padding-10) 
button = Button(text='My first button') 
layout .add_widget (button) 


这 个 按钮 就 添加 到 布局 当中 去 了 : 按钮 的 parent 属性 会 被 设置 为 ; 这 个 按钮 也 会 被 
添加 到 布局 中 的 子 控件 列表 。 要 把 这 个 按钮 从 这 个 布局 中 删 掉 也 很 简单 


layout.remove widget(button) 
移 除了 之 后 ， 这 个 按钮 的 parent 属性 就 会 被 设置 为 None， 也 会 被 从 布局 的 子 控件 列表 中 移 


要 是 想 清空 一 个 控件 中 的 所 有 自 科 技 ， 那 就 用 clear widgets() 方法 就 可 以 了 : 


layout.clear widgets() 


特别 注意 


千 万 别 自己 手动 去 操作 子 控件 列表 ， 除 非 你 确定 自己 掌控 得 非常 深入 透彻 。 因 为 控件 树 是 和 
绘图 树 联 系 在 一 起 的 。 例 如 ， 如 果 你 添加 了 一 个 控件 到 子 控 件 列表 ， 但 没有 添加 这 个 新 子 控 
件 的 画布 到 绘图 树 上 ， 那 么 就 会 出 现 这 种 情况 : 这 个 控件 确实 成 了 一 个 子 控件 ， 但 是 屏幕 上 
不 会 显示 出 来 。 此 外 ， 如 果 你 后 续 使 用 添加 、 移 除 、 清 空 控件 这 些 操作 ， 可 能 还 会 遇 到 问 
题 。 


i& Ji AE TE 


控件 类 实例 的 子 控件 children 列表 属性 中 包含 了 所 有 的 子 控件 。 所 以 可 以 用 如 下 的 方式 来 进 


root = BoxLayout() 
. add widgets to root ... 
for child in root.children: 
print(child) 


然而 ， 这 样 的 操作 可 得 谨 惯 使 用 。 如 果 你 要 用 之 前 一 节 中 提 到 的 方法 来 修改 这 个 子 控件 列表 
电话 ， 请 一 定 用 下 面 这 种 方法 来 做 一 下 备份 : 


for child in root.children[:]: 
# manipulate the tree. For example here, remove all widgets that have a 
# width 
if child.width 100: 
root.remove widget(child) 


默认 情况 下 ， 控 件 是 不 会 对 子 控件 的 尺寸 /位 置 进行 改变 的 。 位 置 属性 pos 是 屏幕 坐标 系 上 的 
绝对 值 ( 除 非 你 使 用 相对 布局 relativelayout ° 这 个 以 后 再 说 ) ， 而 尺寸 属性 size 就 是 一 
个 绝对 的 尺寸 大 小 。 


控件 索引 Z 


控件 绘制 的 顺序 ， 是 基于 各 个 控件 在 控件 树 中 的 位 置 。 添 加 控件 方法 add widget 可 以 接收 
一 个 索引 参数 ， 这 样 就 能 指定 该 新 增 控件 在 控件 树 中 的 位 置 。 


root.add_widget(widget, index) 


索引 值 小 的 控件 会 被 绘制 在 索引 值 大 的 控件 之 上 。 一 定 要 记 住 ， 默 认 值 是 0， 所 以 后 添加 的 
控件 总 会 在 所 有 控件 的 最 顶层 ， 除 非 指定 了 索引 值 。 


整理 布局 


布局 layout 是 一 种 特别 的 控件 ， 它 会 控制 自己 子 控件 的 尺寸 和 位 置 。 有 各 种 不 同 的 布局 ， 这 
些 布局 分 别 为 子 控件 提供 拜托 你 个 的 自动 组 织 整 理 。 这 些 布局 使 用 尺寸 推测 size hint 和 位 
置 推测 pos hint 这 两 个 属性 来 决定 子 控件 children 的 尺寸 size 和 42H pos ° 

盒 式 布 局 BoxLayout: 所 有 控件 充满 整个 空间 ， 以 互相 挨 着 的 方块 的 方式 来 分 布 ， 横 着 或 者 
坚 着 排列 都 可 以 。 子 控件 的 size_hint 属性 可 以 用 来 改变 每 个 子 控件 的 比例 ， 也 可 以 设置 为 
定 尺 寸 。 


Box Layout Grid Layout 


horizontal 


Stack Layout 


Ir-tb 


Anchor Layout 


anchor_x = left 
anchor_y = top 





Float Layout 


no restriction ”no restrictions 
whatsoever. what so ever 





网 格 布局 GridLayout: 以 一 张 网 格 的 方式 来 安排 控件 。 你 必须 指定 好 网 格 的 维度 ， 确 定好 分 
成 多 少 格 ， 这 样 Kivy 才能 计算 出 每 个 元 素 的 尺寸 并 且 确 定 如 何 安排 这 些 元 素 的 位 置 。 


栈 状 布局 StackLayout: 挨 着 放 一 个 个 控件 ， 彼 此 邻近 ， 在 某 一 个 维度 上 有 固定 大 小 ， 而 使 它 
HEARED Elo 这 适合 用 来 显示 相同 预定 义 大 小 的 子 控件 。 


4% A 4/53 AnchorLayout: 一 种 非常 简单 的 布局 ， 只 关注 子 控件 的 位 置 。 将 子 控件 放 在 布局 的 
边界 位 置 。 不 支持 size_hint。 


浮动 布局 FloatLayout: 允许 放置 具 任意 位 置 和 尺寸 的 子 控件 ， 可 以 是 绝对 尺寸 ， 也 可 以 是 相 
对 布局 的 相对 尺寸 。 默认 的 size_hint (1°1) 会 让 每 个 子 控件 都 与 整个 布局 一 样 大 ， 所 以 如 
果 你 多 个 子 控件 就 要 修改 这 个 值 。 可 以 把 size hint 3€ £ (None, None)， 这 样 就 可 以 使 用 
size 这 个 绝对 尺寸 属性 。 控 件 也 支持 pos_hint， 这 个 属性 是 一 个 dict 词典 ， 用 来 设置 相对 布 
局 的 位 置 。 


相对 布局 RelativeLayout: 和 浮动 布局 FloatLayout 差不多 ， 不 同 之 处 在 于 子 控件 的 位 置 是 相 
对 于 布局 空间 的 ， 而 不 是 相对 于 屏幕 。 


想 要 深入 理解 各 种 布局 的 话 ， 可 以 仔细 阅读 各 种 文档 。 
Size_hint 和 pos hint : 


© floatlayout 

*  boxlayout 

e gridlayout 

€  stacklayout 

©  relativelayout 


©  anchorlayout 


size hint 是 一 个 引用 列表 属性 ReferenceListProperty ? 包括 size_hint_x 

和 size_hint_y 两 个 变量 。 接 收 的 变量 值 是 从 0 到 1 的 各 种 数值 ， 或 者 None > 默认 值 为 (1, 
1)。 这 表示 如 果 控 件 处 在 布局 之 内 ， 布 局 将 会 在 两 个 方向 分 配 全 部 尺寸 (相对 于 布局 大 小 ) 给 
该 控件 。 


举 个 例子 ， 设 置 size hint 为 (0.5, 0.8)， 就 会 给 该 控件 widget 分 配 布局 layout A50% 
55 * 8096 高 的 尺寸 。 


例如 下 面 这 个 例子 : 


BoxLayout: 
Button: 
text: 'Button 1' 
4 default size hint is 1, 1, we don't need to specify it explicitly 
# however it's provided here to make things clear 


size hint: 1, 1 


加 载 Kivy B x : 


cd $KIVYDIR/examples/demo/kivycatalog 
python main.py 


把 上 面 代码 中 的 SKIVYDIR 替换 成 你 的 Kivy 安装 位 置 。 在 左边 点 击 标注 有 Box Layout 的 按 
d 。 然 后 将 上 面 的 代码 粘贴 到 窗口 右 侧 的 编辑 器 内 。 


Welcome Auto Reload Render Now 


BoxLayout: 
Button: 
text: ‘Button 1° 
size hint: 1, 1 


[Button 1 





然后 你 就 可 以 看 到 上 图 这 样 的 界面 了 ， 这 个 按钮 Button 会 占据 整个 布局 尺寸 size 的 
100% ° 


修 改 size_hint_x / size_hint ny) A .5 这 就 会 把 控件 Widget 调整 为 布局 layout 的 50% 宽 
度 width /高 度 height ° 


BoxLayout: 

Button: 
text: ‘Button 1 
size_hint: @.5, 





这 时 候 效 果 如 上 图 所 示 ， 虽 然 我 们 已 经 同时 指定 了 size hint x 和 size hint y 为 .5， 但 似 

FRA sqzeshantsx 的 修改 起 作用 了 。 这 是 因为 在 盒 式 布 局 boxlayout 中 ， 

当 orientation 被 设置 为 紧 直 方向 (vertical) 的 时 候 ， size hint y 由 布局 来 控制 ， 而 如 

果 orientation 被 设置 为 水 平方 向 (horizontal) 的 时 候 ， size hint x 由 布局 来 控制 ， 所 以 

这 些 情况 手动 设 定 就 无 效 了 。 这 些 受 控 维 度 ne 是 根据 子 控件 children Æ 爹 式 布局 

boxlayout 中 的 总 编号 来 计算 的 。 在 上 面 的 例 ie 这 个 子 控件 的 size hint y 是 受 控 的 (.5/.5 
1)。 所 以 ， 这 里 控件 就 占据 了 上 层 布局 的 整个 高 


接 下 来 咱们 再 添加 一 个 按钮 Button 到 这 个 布局 layout 看 看 有 什么 


Welcome Auto Reload Render Now 


BoxLayout: 

Button: 
text: ‘Button 1° 

Button: 
text: "Button 2' 


Button 1 Button 2 





Q&A E boxlayout 默认 对 其 所 有 的 子 控件 children 分 配 了 等 大 的 空间 。 在 咱们 这 个 例子 
里 面 ， 比 例 是 50-50， 因 为 有 两 个 子 控件 children 。 那 么 接 下 来 咱们 就 对 其 中 的 一 个 子 控件 
设置 一 下 size_hint， 然 后 看 看 效果 怎么 样 。 


Welcome Auto Reload Render Now 


BoxLayout: 
Button: 
text: ‘Button 1° 
size hint: 98.5, 1 
Button: 
text: 'Button 2' 


Button 1 Button 2 





从 上 图 可 以 看 出 ， 如 果 一 个 子 控件 有 了 一 个 指定 的 size hint ， 这 就 会 决定 该 控件 

Widget 使 用 盒 式 布 局 boxlayout 提供 的 空间 中 的 多 大 比例 ， 来 作为 自己 的 尺寸 size 。 在 
我 们 这 个 例子 中 ， 第 一 个 按钮 Button 的 size hint x 设置 为 了 .5。 那么 这 个 控件 分 配 到 的 
空间 计算 方法 如 下 : 


first child's size_hint divided by 
first child's size_hint + second child's size_hint + ...n(no of children) 


.5/(.5+1) = .333... 


ENA A BoxLayout 的 剩余 宽度 width 会 分 配给 另外 的 一 个 子 控件 children 。 在 我 们 这 个 
例子 中 ， 这 就 意味 着 第 二 个 按钮 Button 会 占据 整个 布局 layout 的 66.66% 宽度 width ° 


修改 size hint 探索 一 下 来 多 适应 一 下 吧 。 

如 果 你 想 要 控制 一 个 控件 Widget 的 绝对 尺寸 size ， 可 以 把 size_hint_x / size_hint_y 当 
中 的 一 个 或 者 两 个 都 设置 成 None， 这 样 的 话 该 控件 的 宽度 width 和 高 度 height 的 属性 值 
就 会 生效 了 。 

pos hint 是 一 个 词典 dict， 默 认 值 是 室 。 相 比 于 size hint ， 布 局 对 pos hint 的 处 理 方式 
有 些 不 同 ， 不 过 大 体 上 你 还 是 可 以 对 pos 的 各 种 属性 设 定 某 个 值 来 设 定 控件 widget 在 父 控 
件 parent 中 的 相对 位 置 (可 以 设 定 的 属性 包括 x , BV. qaght., Stop, Rcenterso, 


center_y ) 9 


咱们 用 下 面 kivycatalog 中 的 代码 来 可 视 化 地 理解 一 下 pos hint 


FloatLayout: 

Button: 
text: "We Will" 
pos: 100, 100 
sizenhint: -2 4 

Button: 
text: "Wee Wiill" 
pos: 200, 200 
size_hint: .4, .2 


Button: 
text: "ROCK YOU!!" 
rosettes oo asi, UR AG 
size_hint: .5, .2 


这 份 代码 的 输出 效果 如 下 图 所 示 : 


FloatLayout: 
Button: 
text: “We Will" 
pos: 168, 188 


size hint: .2, .4 
Button: b 
text: "Wee Wiill 
pos: 2080, 208 ROCK YOU!! 
size hint: .4, .2 
Button: 
text: "ROCK YOU!!” 
pos-nint: [X 4 y 356) 


size hint: 9 “2 








说 了 半天 size_hint |’ 尔 不 妨 自 己 试 试探 索 一 下 pos hint * 来 理解 一 下 这 个 属性 对 控件 位 置 
的 效果 。 


给 布局 添加 背景 


关于 布局 ， 有 一 个 问题 经 常 被 问 道 


“怎么 给 一 个 布局 添加 背景 图 片 /颜色 / 视 频 / 等 等 ..….. 
本 来 默认 的 各 种 布局 都 是 没有 视觉 呈现 的 : 因为 布局 不 像 控 件 ， 布 局 是 默认 不 含有 绘图 指令 
的 。 不 过 呢 ， 还 是 你 可 以 给 一 个 布局 实例 添上 绘图 指令 ， 也 就 可 以 添加 一 个 彩色 背景 了 : 


^S 


在 Python 中 的 实现 方法 : 


from kivy.graphics import Color, Rectangle 


with layout_instance.canvas.before: 
Color(0, 1, ©, 1) # green; colors range from 0-1 instead of 0-255 
self.rect - Rectangle(size-layout instance.size, 


pos-layout instance.pos) 


然而 很 不 幸 ， 这 样 只 能 在 布局 的 初始 化 位 置 以 布局 的 初始 尺寸 绘制 一 个 矩形 。 所 以 还 要 对 布 
局 的 尺寸 和 位 置 变 化 进行 监听 ， 然 后 对 矩形 的 尺寸 位 置 进行 更 新 ， 这 样 才 能 保证 这 个 矩形 一 
绘制 在 布局 的 内 部 。 可 以 用 如 下 方式 实现 : 


with layout_instance.canvas.before: 
Color(0, 1, ©, 1) # green; colors range from 0-1 instead of 0-255 
self.rect - Rectangle(size-layout instance.size, 


pos-layout instance.pos) 


def update rect(instance, value): 
instance.rect.pos - instance.pos 
instance.rect.size - instance.size 


# listen to size and position changes 


layout instance.bind(pos-update rect, size-update rect) 


在 kv 文件 中 : 


FloatLayout: 
canvas.before: 

Color: 
rgba: 0, 1, 0, 1 

Rectangle: 
# self here refers to the widget i.e BoxLayout 
pos: self.pos 
size: self.size 


上 面 的 Kv 文件 中 的 生命 ， 就 建立 了 一 个 隐 含 的 绑 定 : LO Kv KBP 8 US RIT RE T BY 
的 位 置 pos 和 尺寸 size 会 在 浮动 布局 floatlayout 的 位 置 pos 发 生变 化 的 时 候 进 行 更 
新 。 


接 下 来 咱们 把 上 面 的 代码 片段 放 进 Kivy 应 用 里 面 。 


纯 Python 方法 : 


from kivy.app import App 

from kivy.graphics import Color, Rectangle 
from kivy.uix.floatlayout import FloatLayout 
from kivy.uix.button import Button 


class RootWidget(FloatLayout): 


def _init_ (self, **kwargs): 
# make sure we aren't overriding any important functionality 
super(RootWidget, self).__init__(**kwargs) 


# let's add a Widget to this layout 
self .add_widget ( 
Button( 
text="Hello World", 
size_hint=(.5, .5), 
pos_hint={'center_x': .5, 'center y': .5})) 


class MainApp(App): 


deftebusTd(setf): 
self.root - root - RootWidget() 
root.bind(size-self. update rect, pos-self. update rect) 


with root.canvas.before: 
Color(0, 1, ©, 1) # green; colors range from 0-1 not 0-255 
self.rect - Rectangle(size-root.size, pos-root.pos) 

return root 


def update rect(self, instance, value): 
self.rect.pos - instance.pos 
self.rect.size - instance.size 


if name == made 
MainApp().run() 





使 用 Kv 语言 : 


控件 


from kivy.app import App 
from kivy.lang import Builder 


root = Builder.load string(''' 
FloatLayout: 
canvas.before: 
Color: 
rgha o Os al, 
Rectangle: 


# self here refers to the widget i.e FloatLayout 


pos: self.pos 
size: self.size 
Button: 
text: 'Hello World!!' 
size hint: 5) :5 


pos_hint: {'center_x': 


ny 


class MainApp(App): 


def build(self): 
return root 


ar name == ' qain ': 
MainApp().run() 





35; 


'center y': 


5} 
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控件 


上 面 这 两 个 应 用 的 效果 都 如 下 图 所 示 : 


Hello World!! 





给 自 定义 布局 规则 /类 增加 背景 色 


上 面 那 一 段 中 咱们 对 布局 实例 增加 背景 的 方法 ， 如 果 用 到 很 多 歌 布局 里 面 ， 那 就 很 快 变 得 特 
别 麻烦 了 。 要 解决 这 种 需求 ， 就 可 以 基于 布局 类 Layout 创建 一 个 自 定 义 的 布局 子 类 ， 给 自 定 
义 的 这 个 类 增加 一 个 背景 。 


使 用 Python : 
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from kivy.app import App 

from kivy.graphics import Color, Rectangle 
from kivy.uix.boxlayout import BoxLayout 
from kivy.uix.floatlayout import FloatLayout 
from kivy.uix.image import AsyncImage 


class RootWidget(BoxLayout): 
pass 


class CustomLayout(FloatLayout): 


def init (self, **kwargs): 
# make sure we aren't overriding any important functionality 
super(CustomLayout, self). (init (**kwargs) 


with self.canvas.before: 
Color(0, 1, 0, 1) # green; colors range from 0-1 instead of 0-255 
self.rect - Rectangle(size-self.size, pos-self.pos) 


self.bind(size-self. update rect, pos-self. update rect) 


def update rect(self, instance, value): 
self.rect.pos - instance.pos 
self.rect.size - instance.size 


class MainApp(App): 


def build(self): 
root - RootWidget() 
c = CustomLayout( ) 
root.add widget(c) 
c.add widget( 
AsyncImage( 
sourcez"http://www.everythingzoomer.com/wp-content/uploads/2013/01/Mon 
day-joke-289x277.jpg", 
size hint- (1, .5), 
pos hint-('center x':.5, 'center y':.53)) 
root .add_widget (AsyncImage(source='http://www.stuffistumbledupon.com/wp-conten 
t/uploads/2012/05/Have - you-seen- this -dog- because -its-awesome-meme-puppy-doggy.jpg')) 
c = CustomLayout( ) 
c.add widget( 
AsyncImage( 
source="http://www. stuffistumbledupon.com/wp-content/uploads/2012/04/G 
et-a-Girlfriend-Meme-empty-wallet.jpg", 
size hint- (1, .5), 
pos_hint={'center_x':.5, 'center_y':.5})) 
root .add_widget(c) 
return root 


aW name S= cel eee 





MainApp().run() 


控件 


使 用 Kv 语言 : 


from kivy.app import App 

from kivy.uix.floatlayout import FloatLayout 
from kivy.uix.boxlayout import BoxLayout 
from kivy.lang import Builder 


Builder.load_string(''' 
<CustomLayout> 
canvas.before: 
Color: 
oda (0; al, OO al 
Rectangle: 
pos: self.pos 
size: self size 


<RootWidget> 
CustomLayout: 
AsyncImage: 
source: 'http://www.everythingzoomer.com/wp-content/uploads/2013/01/Monday 
-joke-289x277.jpg' 
size thant: les 
pos hint: t centenexir eb center <5) 
AsyncImage: 
source: 'http://www.stuffistumbledupon.com/wp-content/uploads/2012/05/Have-you 
-seen-this-dog-because-its-awesome-meme-puppy-doggy.jpg' 
CustomLayout 
AsyncImage: 
source: 'http://www.stuffistumbledupon.com/wp-content/uploads/2012/04/Get- 
a-Girlfriend-Meme-empty-wallet.jpg' 
size hint: 1, 5 
possunt decenter xno, Ecenbenrey 5 


US 


class RootWidget(BoxLayout ) : 
pass 


class CustomLayout(FloatLayout): 
pass 


class MainApp(App): 


def build(self): 
return RootWidget() 


m name == ' qain ': 
MainApp().run() 





上 面 这 两 个 应 用 的 效果 都 如 下 图 所 示 : 


oe Main eee 


| HAVE YOU SEEN 
me THIS DOG 


LEG? 
UNLEADED a w 10 


Fray) Se) BECAUSE IT’S 
UNLEADED B 0 th 10 AWESOME!!! 


ARM; | v 

9 X 

paa; 10 H. Y 
B 





在 自 定义 布局 类 中 定义 了 背景 之 后 ， 就 是 要 确保 在 自 定义 布局 的 各 个 实例 中 使 用 到 这 个 新 特 
小 o 


首先 ， 要 在 全 局 上 增加 一 个 图 形 或 者 颜色 给 内 置 的 Kivy 布局 的 背景 ， 这 就 需要 将 所 用 布局 的 
默认 Kv 规则 进行 尾 盖 。 


就 拿 网 格 布局 GridLayout 举例 吧 : 


<GridLayout> 
canvas.before: 


Color: 
rgba: 0, 1, 0, 1 
BorderImage: 
source: '../examples/widgets/sequenced images/data/images/button white.png' 


pos: self.pos 
size: self.size 


IE —À—MM—— ÉÁÓóÓ Mss | 


接 下 来 把 这 段 代码 放 到 一 个 Kivy 应 用 里 面 : 


控件 


from kivy.app import App 
from kivy.uix.floatlayout import FloatLayout 
from kivy.lang import Builder 


Builder.load string(''' 
<GridLayout> 
canvas.before: 
BorderImage: 
# BorderImage behaves like the CSS BorderImage 
border: 10, 10, 10, 10 
source: '../examples/widgets/sequenced_images/data/images/button_white. png 


pos: self.pos 
size: self.size 


<RootWidget> 
GridLayout: 
size hinto 9 9 
possihanitwenicentenmo >) center yd b 
rows:1 
Label: 
text: "I don't suffer from insanity, I enjoy every minute of it" 
text_size: self.width-20, self.height-20 
valign: 'top' 
Label: 
text: "When I was born I was so surprised; I didn't speak for a year and a 
adf 
text size: self.width-20, self.height-20 
valign: 'middle' 
halign: 'center' 
Label: 
text: "A consultant is someone who takes a subject you understand and make 
S it sound confusing" 
text size: self.width-20, self.height-20 
valign: 'bottom' 
halign: 'justify' 
y) 


class RootWidget(FloatLayout): 
pass 
class MainApp(App): 


def build(self): 
return RootWidget() 


ag name == maan 





MainApp().run() 
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效果 大 概 如 下 图 所 示 : 


I don't suffer from insanity, I 
| enjoy every minute of it 


When I was born I was so 
surprised; I didn't speak for a 
year and a half. 


A consultant is someone who 
takes a subject you understand 
and makes it sound confusing 





我 们 已 经 对 网 格 布局 GridLayout 类 的 规则 进行 了 履 盖 ， 所 以 接 下 来 在 应 用 中 使 用 这 个 类 就 都 
会 显示 那 幅 图 片 了 。 


动画 背景 怎么 弄 呢 ? 


就 像 在 矩形 Rectangle/ 边界 图 像 Borderlmage /椭圆 Ellipse/ 等 里 面 添加 设置 绘图 指令 一 样 ， 可 
以 用 一 个 特定 的 纹理 属性 texture 


Rectangle: 
texture: reference to a texture 


可 以 用 下 面 的 代码 实现 一 个 动画 背景 : 


n kivy.app import App 
m kivy.uix.floatlayout import FloatLayout 
kivy.uix.gridlayout import GridLayout 





m kivy.uix.image import Image 






n kivy.properties import ObjectProperty 


H 





from kivy.lang import Builder 


控件 


Builder.load string(''' 
<CustomLayout> 
canvas.before: 
BorderImage: 

# BorderImage behaves like the CSS BorderImage 
border: 10, 10, 10, 10 
texture: self.background_image.texture 
pos: self.pos 
size: SOL size 


<RootWidget> 
CustomLayout: 
size_hint: .9, .9 
possunt ceniepexu eb “center ya: 5r 
rows:1 
Label: 
text: "I don't suffer from insanity, I enjoy every minute of it" 
text size: self.width-20, self. height-20 
valign: 'top' 
Label: 
text: "When I was born I was so surprised; I didn't speak for a year and a 
halini 
text size: self.width-20, self.height-20 
valign: 'middle' 
halign: 'center' 
Label: 
text: "A consultant is someone who takes a subject you understand and make 
s it sound confusing" 
text_size: self.width-20, self.height-20 
valign: 'bottom' 
halign: 'justify' 
on) 


class CustomLayout(GridLayout ) : 


background_image = ObjectProperty( 
Image ( 
source='../examples/widgets/sequenced_images/data/images/button_white_anim 
ated: zipi, 
anim_delay=.1)) 


class RootWidget(FloatLayout): 
pass 
class MainApp(App): 


def burtrd(self): 
return RootWidget() 
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aly name == eis 





MainApp().run() 


要 理解 这 里 到 底 发 生 了 什么 ， 得 从 第 13 行 开始 看 : 


texture: self.background image.texture 


这 里 是 指 samen Borderlmage 的 纹理 属性 在 背景 图 像 background image 的 纹理 属性 
发 生 更 新 的 时 候 进 行 同步 更 新 。 背 景 图 像 background image 属性 的 定义 是 在 第 40 fT: 


background_image = ObjectProperty(... 


ik — 6) RAG 3 3433 X BR background image 设置 成 一 个 对 得 属性 objectProperty ， 这 样 就 
可 以 在 其 中 添加 一 个 图 形 控件 image 。 图 像 控 件 有 一 个 纹理 属性 (texture property) ; 在 前 
面 的 self.background_image.texture 这 名 代码 中 ， 就 是 建立 了 一 个 名 为 texture 的 到 这 个 属性 
的 引用 。 peek Image 支持 动画 (animation) : 随 着 动画 的 改变 ， 图 像 的 纹理 会 同步 更 

新 ， 在 这 个 过 程 中 ， 边 界 图 像 Borderlmage 指令 的 texture 纹理 属性 也 会 同步 更 新 。 


( 译 者 注 : texture of Borderlmage instruction， 这 里 我 对 instruction 的 翻译 应 该 是 不 太 对 
的 ， 不 过 我 还 没 理 清楚 该 怎么 表述 。 ) 


也 可 以 直接 传递 自 定 义 数 据 到 纹理 属性 texture。 更 多 细节 可 以 参考 纹理 Texture 的 文档 。 


网 状 布局 


咽 ， 看 看 这 个 过 程 如 何 扩 展 是 很 有 趣 的 。 


尺寸 和 位 置 度量 


Ky Ai Se pixels ug E ae 个 单位 来 表达 。 你 也 可 以 用 其 他 
单位 来 衡量 ， 在 跨 平 台 多 种 设备 的 时 候 ， 这 有 助 于 实现 更 好 的 连续 性 体验 〈 这 些 设备 会 把 尺 
寸 自动 转换 到 像素 ) © 


可 用 单位 包括 pt * mm * cm, inch * dp and sp 。 可 以 在 度量 文档 metrics 中 了 解 更 
多 相关 内 容 。 


你 还 可 以 探索 一 下 屏幕 模块 screen 的 用 法 ? 这 个 可 以 模拟 出 不 同 设 备 的 屏幕 供 测 试 应 用 9 


AR FI REGE E ER S AT HRD Sl 


如 果 你 的 应 用 程序 要 包含 多 个 程序 ， 那 可 能 就 需要 从 一 个 屏幕 screen 到 另 一 个 屏幕 

Screen 提供 一 个 导航 的 通道 9 幸运 的 是 ? 正好 有 一 个 屏幕 管理 器 类 ScreenManager ^? 这 个 类 
允许 你 来 定义 分 开 的 各 个 屏幕 ? 设置 屏幕 管理 器 的 TransitionBase 就 可 以 实现 从 一 个 屏幕 到 
另 一 个 屏幕 的 跳 转 导航 。 


Title: Kivy Graphics Date: 2017-02-12 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : AW 


这 一 章节 比 前 两 章节 简单 很 多 ， 翻 译 的 也 比较 顺 了 。 


Kivy 中 控件 图 形 呈 现 是 使 用 Canvas 完 成 的 ， 可 以 将 其 看 作 一 个 无 限 的 绘图 板 ， 也 是 一 组 绘图 
指令 。 有 很 多 种 绘图 指令 都 可 以 应 用 或 者 添加 到 你 的 Canvas 伤 ， 不 过 总 体 上 分 为 两 类 : 


@ context instructions 环境 指令 


e vertex instructions Ji 点 指令 


context instructions 环境 指令 不 绘制 任何 图 形 2 但 会 改变 vertex instructions 顶 点 指令 的 


绘制 结果 。 


Canvas 都 包含 两 个 指令 分 支 i 分 别 是 canvas .before 和 canvas.after 这 两 种 指令 群 o 这 两 组 
指令 分 别 在 canvas 图 形 绘制 前 后 执行 。 绘 制 前 的 会 被 绘制 的 图 形 尾 盖 掉 ， 绘 制 后 的 会 覆盖 在 
图 形 上 层 。 这 些 指令 都 在 用 户 对 它们 读 取 之 后 才 会 被 创建 。 


要 对 一 个 控件 添加 Canvas 绘 图 指令 ， 需 要 使 用 Canvas 环 境 指令 : 


class MyWidget (Widget): 
def dqmateeeset c e S kwatgs)l 
super(MyWidget, self). (init (**kwargs) 
with self.canvas: 
# add your instruction for main canvas here 


# 这 里 是 增加 一 个 座位 主 绘图 的 指令 


with self.canvas.before: 
# you can use this to add instructions rendered before 


# 这 里 可 以 在 绘图 之 前 添加 指令 


with self.canvas.after: 
# you can use this to add instructions rendered after 


# 这 里 可 以 在 绘图 之 后 添加 指令 


环境 指令 


环境 指令 是 用 于 操作 opengl 环 境 。 可 以 旋转 ， 翻译 和 缩放 画布 。 还 可 以 附加 纹理 或 更 改 绘图 
颜色 。 下 面 这 段 代码 里 面 的 是 最 常用 到 的 更 改 颜 色 的 指令 ， 其 他 的 环境 指令 也 都 很 有 用 处 : 


with self.canvas.before: 
Color(i, ©, .4, mode='rgb') 


绘图 指令 


绘图 指令 可 简 可 繁 ， 最 简单 的 比如 画 一 个 多 边 形 ， 更 复杂 的 比如 绘制 网 格 或 者 贝 塞 尔 曲线 都 
可 以 : 


with self.canvas: 
# draw a line using the default color 
# AXUVMEB—-KA 


Line(points=(x1, y1, x2, y2, x3, y3)) 


# lets draw a semi-transparent red square 
# 接 下 来 画 一 个 半 透 明 的 红 方 块 


Color(i, ©, 0, .5, mode='rgba') 
Rectangle(pos=self.pos, size=self.size) 


有 时 候 可 能 需要 把 之 前 添加 到 Canvas 绘 图 上 的 指令 进行 更 改 或 者 删除 ， 这 可 以 有 很 多 种 办 
法 ， 要 根据 具体 需求 来 选择 : 


可 以 给 指令 创建 一 个 引用 然后 对 其 进行 更 新 : 


class MyWidget(Widget): 
def init (self, **kwargs): 
super(MyWidget, self). init (**kwargs) 
with self.canvas: 
self.rect = Rectangle(pos=self.pos, size=self.size) 


self.bind(pos-self.update rect) 
self.bind(size-self.update rect) 


def update-rect(self, *args): 
self.rect.pos - self.pos 
self.rect.size - self.size 


或 者 也 可 以 清空 Canvas 画 布 然后 重新 画 : 


class MyWidget(Widget): 
def init (self, **kwargs): 
super(MyWidget, self). (init (**kwargs) 
self.draw my stuff() 


self.bind(pos-self.draw my stuff) 
self.bind(size-self.draw my stuff) 


def draw my stuff(self): 
self.canvas.clear() 


with self.canvas: 
self.rect = Rectangle(pos=self.pos, size=self.size) 


要 注意 更 新 指令 的 方法 是 更 好 的 选择 ， 因 为 这 样 减少 了 开销 ， 并 且 避 免 了 创建 新 指令 。 


Title: Kivy Pack Windows Date: 2017-03-01 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 打包 为 Windows 系统 可 
执行 文件 


英文 原文 
特别 注意 


本 文档 仅 适 用 于 1.9.1 以 及 更 新 版 本 的 Kivy 。 


要 打包 Windows 平台 的 应 用 程序 ， 只 能 在 Windows 操作 系统 下 完成 。 另 外 一 定 要 注意 ， 本 
文 后 续 内 容 中 都 是 在 Wheels 安装 的 Kivy 下 通过 测试 的 ， 如 果 你 用 其 他 安装 方法 ， 参 考 结尾 


部 分 吧 。 


打包 出 来 的 程序 是 32 位 还 是 64 位 只 取决 于 你 打包 使 用 的 Python， 而 不 取决 于 Windows 操 
作 系 统 的 版 本 。 


依赖 包 
e 最 新 版 本 的 Kivy (参考 安装 指南 Installation on Windows) 
e Pylnstaller 3.1 或 者 更 新 的 版 本 ( pip install --upgrade pyinstaller ) ^ 


( 译 者 注 : Pylnstaller 目前 (20174-03014 ) 还 不 支持 Python 3.6 哦 ~， 好 多 朋友 都 坑 到 
这 里 了 ， 所 以 推荐 使 用 3.5.2。) 


PyInstaller 的 基本 用 法 


本 节 内 容 是 要 让 Pylnstaller (3.1 或 者 更 新 版 本 ) 包含 Kivy 的 Hook ( 钓 子 ，Windows 消息 
处 理 机 制 的 一 个 平台 ) o RARUA Hook ， 下 面 的 样 例 代码 需要 稍微 修改 一 下 。 参 考 A 
盖 默 认 Hook 。 


打包 一 个 简单 的 APP 


这 个 例子 里 面 ， 咱 们 要 把 样 例 中 的 touchtracer 这 个 项 目 进行 打包 ， 并 且 添 加 一 个 自 定 义 图 
标 。 这 里 Kivy 的 样 例 目录 要 注意 ， 如 果 是 用 wheels 安装 的 ， 在 python\\share\\kivy- 
examples 这 个 位 置 ， 如 果 从 github 上 面 下 载 的 ， 就 在 kivy\\examples 这 个 位 置 。 为 了 避免 


混乱 ， 这 里 就 用 examples-path 来 指 代 这 个 目录 的 完整 路 径 。 然 后 touchtracer 这 个 样 例 在 
examples -path\\demo\\touchtracer 这 个 文件 夹 里 ， 代 码 文件 是 main.py ° 


1 确保 Python 


打开 命令 行 确保 Python 包含 在 环境 变量 内 ， 也 就 是 说 ， 输 入 python 会 出 现 解释 器 提示 符 。 
( 译 者 注 : cmd 或 者 powershell 都 可 以 ， 更 推荐 用 后 者 ， 语 法 和 Bash 比较 相似 。) 


创建 文件 夹 


在 要 打包 APP 的 位 置 创建 一 个 文件 夹 。 比 如 咱们 这 次 就 创建 一 个 名 字 为 Touchapp 的 文件 
夹 ， 然 后 用 类 似 cd Touchapp 这 样 的 命令 进入 到 这 个 新 建 目录 内 。 之 后 输入 : 


python -m PyInstaller --name touchtracer examples-path\demo\touchtracer\main.py 


还 可 以 增加 一 个 icon.ico 文件 到 这 个 应 用 目录 ， 这 样 就 可 以 让 程序 有 自己 的 图 标 了 。 如 果 没 
有 自己 的 ico 图 标 文件 ， 可 以 把 你 的 icon.png 文件 转换 成 ico， 用 这 个 ConvertlCO 在 线 的 应 
用 就 可 以 了 。 保 存 icon.ico 到 touchtracer 这 个 目录 里 面 ， 然 后 输入 : 


python -m PyInstaller --name touchtracer --icon examples-path\demo\touchtracer\icon.ic 
o examples-path\demo\touchtracer\main. py 


更 多 其 它 选 项 ， 请 参考 Pylnstaller E 7 769] » 


3 编辑 配置 文件 


在 TouchApp 里 面 会 有 一 个 配置 文件 touchtracer.spec ° 咱们 需要 编辑 修改 一 下 这 个 文件 ， 
在 里 面 增加 一 些 依赖 包 的 hook， 这 样 才能 保证 正确 创建 exe。 接 下 来 就 是 打开 编辑 器 了 ， 爱 
用 哈 都 行 ， 然 后 在 配置 文件 的 开头 添加 上 下 面 这 名 : (这 里 是 假设 用 的 是 sdl2 ， 现 在 Kivy R 
认 使 用 这 个 ) 


from kivy.deps import sdl2, glew 


， 用 搜索 ， 找 到 coLLECT() 这 个 位 置 ， 添 加 上 touchtracer 用 到 的 其 他 文件 
sania kv, particle.png, 等 等 ) : 修改 示例 中 的 行 位 置 ， 添 加 一 个 Tree() 对 象 ， 例 如 
这 里 的 是 Tree('examples-path\\demo\\touchtracer\\') ° 这 个 Tree() 会 搜索 在 当前 这 个 

touchtracer 文件 夹 的 所 有 文件 ， 并 添加 到 你 最 终 打包 的 程序 中 。 


要 添加 额外 的 依赖 包 ， 就 要 在 COLLECT 的 第 一 个 关键 词 参数 的 前 面 ， 为 每 一 个 依赖 包 的 路 
径 添 加 一 个 Tree 对 象 。 例 如 下 面 的 就 是 以 *[Tree(p) for p in(sdl2.dep bins + 
glew.dep bins)] 为 例 : 


coll = COLLECT(exe, Tree('examples-path\\demo\\touchtracer\\'), 
a.binaries, 
a.zipfiles, 
a.datas, 
*[Tree(p) for p in (sdl2.dep bins + glew.dep bins)], 
strip-False, 
upx-True, 
namez'touchtracer') 


4 进行 构建 
接 下 来 就 用 TouchApp 里 面 这 个 spec 配置 文件 来 进行 构建 了 : 


python -m PyInstaller touchtracer.spec 


5 生成 位 置 


编译 好 的 包 会 在 TouchApp\dist\touchtracer 这 个 目录 。 


使 用 gstreamer 创建 一 个 视频 应 用 

接 下 来 就 是 修改 一 下 上 面 的 这 个 样 例 了 ， 这 回 要 打包 的 APP 是 一 个 使 用 了 gstreamer 的 视频 
应 用 。 咱 们 这 回 用 样 例 中 的 视频 播放 器 的 例子 videoplayer ， 代 码 在 examples- 
path\widgets\videoplayer.py ° 另外 创建 一 个 名 FA VideoPlayer 的 文件 夹 ， 然后 在 命令 行 


中 进入 到 这 个 文件 夹 ， 之 后 操作 如 下 : 


python -m PyInstaller --name gstvideo examples-path\widgets\videoplayer.py 


这 回 要 修改 gstvideo.spec 这 个 文件 。 跟 上 文 的 方法 类 似 ， 也 就 是 把 gstreamer 的 依赖 包 放 
进去 : 
from kivy.deps import sdl2, glew, gstreamer 


然后 就 是 增加 Tree() 来 包含 好 要 用 的 视频 文件 ， Tree('examples-pathNNwidgets') 和 
gstreamer 依赖 都 得 再 好 ， 大 概 如 下 所 示 : 


coll = COLLECT(exe, Tree('examples-path\\widgets'), 
a.binaries, 
a.zipfiles, 
a.datas, 
*[Tree(p) for p in (sdl2.dep bins + glew.dep_bins + gstreamer.dep bins) 


], 
strip=False, 
upx=True, 
name='gstvideo' ) 


接 下 来 就 是 使 用 videoPlayer 文件 夹 中 的 这 个 spec 配置 文件 来 进行 构建 了 : 


python -m PyInstaller gstvideo.spec 


然后 你 就 能 在 VideoPlayer\dist\gstvideo 这 个 位 置 找到 gstvideo.exe 这 个 文件 了 ， 运 行 一 下 
就 能 播放 视频 了 。 


特别 注意 


如 果 你 用 了 Pygame， 或 者 你 打包 的 程序 需要 Pygame， 那 在 你 的 spec 文件 里 面 就 还 得 添加 
如 下 的 代码 ， 在 import 导入 语句 的 后 面 添加 (详情 参考 kivy issue #1638) 


def getResource(identifier, *args, **kwargs): 
if identifier == 'pygame_icon.tiff': 
raise IOError() 
return | original getResource(identifier, *args, **kwargs) 


import pygame.pkgdata 


-original getResource = pygame.pkgdata.getResource 
pygame.pkgdata.getResource - getResource 


xm x SEA Hook 


包含 / 移 除 视频 音频 以 及 缩小 应 用 体积 


PyInstallers 默认 会 将 MM 用 到 的 所 有 核心 模块 和 这 些 模块 的 依赖 包 ， 全 部 都 添加 成 hook ° 
比如 音频 ， 视 频 ， 拼 写 等 等 (然而 gstreamer 的 dll 还 是 需要 你 用 Tree) 来 手动 添加 ， 参 考 
-Ex) 。 有 的 Hook 到 或 者 想 要 缩小 应 用 的 体积 ， 就 都 可 以 尝试 着 移 除 一 些 模块 ， 比 
如 如 果 没 有 用 到 音频 和 视频 ， 就 可 以 用 自 定 义 的 Hook 了 。 


Kivy 在 hookspath() 提供 了 可 选 的 Hook。 


此 外 ， 当 且 仅 当 Pylnstaller 没有 上 默认 的 hook 的 时 候 ， 就 必须 得 提供 一 个 runtime hooks() ° 
覆盖 hook 的 时 候 ， 这 个 runtime hooks() PERR Š ° 


可 选 自 定义 的 hookspath() hook 不 包含 任何 Kivy 的 provider。 要 添加 电话 ， 就 要 

用 get deps minimal() DE get deps all() 来 添加 。 可 以 看 看 相 关 的 文档 以 

及 pyinstaller_hooks 来 了 解 更 多 信息 (Ru get deps all() 跟 上 默认 的 hook 一 样 ， 都 是 把 所 
有 provider 都 添加 进去 ; 而 get deps minimal() 只 添加 在 应 用 程序 运行 的 时 候 加 载 了 的 内 


[Xd 


Ay L 


这 两 个 方法 都 提供 了 一 个 Kivy 隐藏 导入 列表 ， 以 及 排除 的 导入 ， 可 以 传递 出 来 给 


Analysis ° 


还 可 以 生成 一 个 自 定义 hook， 一 个 个 列 出 每 一 个 kivy 的 provider 模块 ， 然 后 把 其 中 用 不 上 的 
就 注释 掉 就 行 了 。 


参考 pyinstaller_hooks . 


要 在 上 面 的 例子 中 使 用 自 定义 hook， 要 按照 下 面 给 出 的 范例 来 修改 ， 以 hookspath() 和 
runtime_hooks (必要 情况 下 ) ， 然 后 是 **get deps minimal() 或 者 **get_deps_all() 来 制 
定好 各 种 provider 。 


例如 ， 增加 了 ATE 6] from kivy.tools.packaging.pyinstaller_hooks import 
get deps minimal, get deps all, hookspath,runtime hooks ? 然后 按照 如 下 方式 修 


改 Analysis 


a = Analysis(['examples-path\\demo\\touchtracer\\main.py'], 


hookspath=hookspath(), 
runtime_hooks=runtime_hooks(), 


**get_deps_all()) 


上 面 这 个 实际 上 跟 默 认 hook 一 样 包含 全 部 了 。 或 者 可 以 : 


a = Analysis(['examples-path\\demo\\touchtracer\\main.py'], 


hookspath=hookspath(), 
runtime_hooks=runtime_hooks(), 


**get_deps_minimal(video=None, audio=None) ) 


这 样 就 是 移 除 了 声音 视频 的 provider， 这 就 只 加 载 了 用 到 的 核心 模块 了 。 


关键 就 是 要 提供 自 定义 的 hookspath() ， 这 个 默认 并 不 会 列 出 全 部 的 kivy provider ， 而 是 手 
动 的 来 设 定 隐藏 导入 的 模块 和 需要 用 的 provider， 通 过 get_deps_minimal() 来 移 除 用 不 上 的 模 
块 (比如 上 面 的 是 声音 影像) 。 


其 他 安装 方式 


前 面 的 这 些 例 子 都 用 到 了 *[Tree(p) for p in (sdl2.dep bins + glew.dep bins + 
gstreamer.dep bins)], 这 样 的 语 名 来 保证 ee 把 所 有 依赖 包 用 到 的 dll 都 添加 进去 。 如 
果 不 是 用 wheel 的 方法 安装 的 Kivy， 那 么 这 些 命令 就 很 可 能 失败 ， 比 如  kivy.deps.sdl2 可 
能 就 无 法 导入 。 这 时 候 ， 你 就 必须 得 找到 这 些 gll 文件 的 位 置 ， 然 后 手动 地 一 个 个 传递 给 

Tree 类 ， 传 递 方法 和 上 面 说 的 基本 差不多 了 。 


( 译 者 注 : Windows 平台 还 是 推荐 用 wheel 二 进 制 安装 ， 省 心 多 了 。 ) 


Title: Kivy Android Date: 2017-03-07 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : KV Android 详细 指南 


在 Android 设备 上 ， 只 要 是 支持 OpenGL ES 2.0 (至 少 为 Android 2.2 以 及 其 后 的 版 本 ) ， 
就 基本 都 能 运行 Kivy 应 用 程序 。OpenGL ES 2.0 基本 上 是 现代 设备 的 标准 了 ; 根据 谷歌 的 报 
道 说 ， 至 少 有 99.9% 的 设备 都 是 支持 的 。 

Kivy 的 APK 就 是 常规 的 Android APP， 和 其 他 的 APP 一 样 可 以 四 处 发 布 ， 比 如 谷歌 Play 商 
店 等 等 。 在 暂停 或 者 重启 的 时 候 这 些 应 用 的 行为 也 都 很 正常 ， 下 面 要 介绍 道 的 是 Kivy APP 用 
到 的 Android 服务 和 需要 用 到 的 大 多 数 常规 的 Java API 。 

下 面 的 内 容 依次 讲解 了 如 何 针对 Android 平台 打包 APP ， 在 设备 上 调试 APP， 以 及 使 用 震 
动 或 者 读 取 传感器 等 等 Android API » 


针对 Android 平台 打包 APPT 


Kivy 项 目 提供 了 针对 Android 平台 打包 APP 所 需 的 全 部 必 备 工具 ， 可 以 构建 单个 的 APK 文 
件 发 布 到 谷歌 Play 市 场 之 类 的 应 用 商店 。 详 细 内 容 可 以 参考 针对 Android 打包 应 用 程序 的 英 
文 原 版 文档 或 者 中 文 翻译 版 本 : 个 人 博客 地 址 ， 知 乎 专栏 地 址 。 


在 Android 设备 上 调试 APPI 

通过 Android Logcat 流 ， 可 以 观察 代码 的 常规 输出 (比如 stdout’ stderr) ， 也 可 以 查看 常规 
的 Kivy 日 志 。 这 需要 使 用 adb 来 查看 ，adb 包含 在 Android SDK 内 。 这 首先 就 要 求 你 再 设 
备 上 开启 开发 者 模式 ， 然 后 启用 USB 调试 功能 来 启用 adb， 接 着 把 设备 连接 到 计算 机 ， 在 终 


端 中 运行 下 面 的 命令 : 


adb logcat 


这 样 就 能 看 到 日 志 输 出 了 ， 包 括 标准 输出 和 出 错 信 息 ( stdout/stderr ) 以 及 Kivy 的 日 志 。 


如 果 你 用 Buildozer 打包 的 APP > RLA TAE adb 工具 没有 包含 在 你 的 $pATH 环境 变量 中 ， 
这 样 上 面 的 命令 就 可 能 没有 效果 。 这 时 候 可 以 用 下 面 的 方法 : 


buildozer android logcat 


面 这 样 就 是 运行 了 Buildozer 伴随 安装 PU adb 工具 ， 或 者 还 可 以 
去 $HOME/.buildozer/android/platform 这 个 目录 找到 Buildozer 伴 随 安装 的 SDK。 


或 者 还 可 以 下 载 Kivy Launcher 来 运行 和 调试 应 用 程序 。 如 果 用 这 种 方法 运行 Kivy 应 用 程序 , 
可 以 在 你 的 应 用 程序 所 在 目录 下 找到 一 个 名 字 为 /.kivy/logs 的 子 目 录 ， 里 面 就 是 日 志 
件 。 


使 用 Android APIT 
虽然 Kivy 是 一 个 Python 框架 ，Kivy 项 目 也 还 维护 了 一 套用 来 调用 常规 Java API 的 工具 ， 可 
以 用 来 处 理 震 动 、 传 感 器 、 发 送 短信 或 邮件 等 等 。 


对 新 用 户 来 说 ， 推 荐 阅读 Plyer。 要 想 有 更 深入 的 使 用 或 者 调用 一 些 目前 没有 封装 的 API， 可 
以 直接 使 用 Pyjnius。Kivy 还 内 置 了 一 个 Android 模块 来 实现 Android 的 一 些 基础 功能 。 


在 Kivy wiki 上 可 以 找到 用 户 提供 的 Android 代码 和 样 例 。 


Plyeri 


Plyer 是 一 个 Python 风格 的 ， 独 立 于 平台 的 API， 用 于 使 用 各 种 平台 上 都 普遍 具有 的 功能 ， 
peas 。 其 设计 思路 是 你 的 应 Cr Plyer 有 函数， 例如 给 用 户 一 个 消 

通知 ， 然 后 Ply 会 处 理 在 不 同 的 平台 或 者 操作 系统 下 分 别 如 何 把 这 件 事 完 成 。 在 Plyer 的 内 
部 ， 在 Android 平台 使 用 的 是 Pyjnius， 在 iOS f Pyobjus， 在 桌面 平台 又 用 了 其 他 
的 特定 API 。 


例如 ， 下 面 的 代码 就 会 让 你 的 Android 设备 震动 ， 或 者 当 你 在 其 他 平台 不 恰当 地 使 用 的 时 候 
就 会 跑 出 一 个 NotImplementError， 例 如 在 桌面 平台 等 没有 对 应 硬件 的 情况 下 : 


from plyer import vibrator 
vibrator.vibrate(10) # vibrate for 10 seconds 


Plyer 支持 的 API 越 来 越 多 了 ， 可 以 在 Plyer GitHub X 049 README 文件 中 查看 完整 的 支持 
列表 o 
PyjniusT 


Pyjnius 是 一 个 Python 模块 ， 它 允许 你 直接 在 Python 中 读 取 Java 类 ， 自 动 转换 参数 成 正确 
的 类 型 ， 还 允许 你 把 Java 的 运行 结果 转换 给 Python 。 


Pyjnius 可 以 从 它 的 GitHub 地 址 下 载 获得 ， 并 且 有 一 份 详细 的 文档 。 


下 面 的 代码 是 一 个 简单 的 小 例子 ， 展 示 了 如 何 使 用 Pyjnius 来 读 取 常 规 的 Android Z% API > 
就 跟 上 面 Plyer 的 代码 效果 一 样 : 


x 


# 'autoclass' 接收 一 个 Java 类 ， 然 后 打包 给 Python; 


from jnius import autoclass 


# Context X Android API 中 一 个 常用 的 Java X; 
Context - autoclass('android.content.Context') 


} 


# PythonActivity 是 在 python-for-android AW Kivy bootstrap app 提 人 


共 的 一 个 


PythonActivity = autoclass('org.renpy.android.PythonActivity') 


里 的 PythonActivity 存储 了 一 个 指向 当前 运行 的 Activity 的 引用 ; 





# 我 们 要 用 它 来 读 取 震动 服务 


activity = PythonActivity.mActivity 


# 底下 的 这 个 振动 器 代码 和 Java 里 面 基本 一 样 的 ; 
vibrator = activity.getSystemService(Context.VIBRATOR SERVICE) 


vibrator.vibrate(10000) # 这 个 值 是 毫秒 为 单位 ， 这 里 设置 的 10 000 毫秒 相当 于 10 秒 


上 面 的 代码 直接 用 了 Java API 函数 来 调用 了 振动 器 ，Pyjnius 自动 把 API 转换 出 给 了 Python 
代码 使 用 ， 而 又 把 我 们 的 调用 都 回 传 给 了 Java。 相 比 Plyer 的 实现 ， 这 种 方法 更 繁琐 一 些 ， 
也 更 像 Java 的 风格 ， 在 这 个 例子 中 没有 什么 优势 。 不 过 Plyer 也 并 没有 对 Pyjnius 的 所 有 
API 都 进行 了 封装 。 


Pyjnius 还 有 一 个 强大 的 功能 就 是 实现 Java 接口 ， 这 在 封装 某 些 APL 的 时 候 非 常 重 要 ， 不 过 
这 里 就 不 详细 讲 这 么 多 了 ， 有 兴趣 的 话 去 Pyjnius 的 官方 文档 来 了 解 更 深层 次 内 容 吧 。 


Android 模块 本 


Python-for-android 项 目 中 包含 了 一 个 Python 模块 (实际 上 是 用 cython 封装 的 Java) 来 读 
取 一 系列 有 限 的 Android API « 这 个 很 大 程度 上 已 经 被 上 面 的 Pyjnius 和 Pyler 取代 了 ， 因 为 
后 者 更 加 灵活 方便 ， 不 过 有 时 候 可 能 这 个 模块 还 有 些 用 处 。 所 有 可 用 的 文档 都 可 以 在 python- 
for-android 官方 文档 中 查阅 到 。 


其 中 就 包括 了 计 费 /应 用 内 购买 的 代码 ， 以 及 创建 或 者 读 取 某 些 Android 服务 的 代码 ， 其 他 
工具 目前 还 没 能 提供 这 方面 的 功能 。 


项 目 状态 以 及 通过 测试 的 设备 村 


前 面 的 章节 讲述 了 Kivy 在 Android 系统 的 构建 工具 ， 以 及 他 们 各 自 的 缺陷 还 有 就 是 已 知 能 够 
使 用 的 设备 。 


Android 工具 链 现在 挺 稳 定 的 ， 一 定 程度 上 基本 能 适用 于 各 种 设备 了 ; Kivy 的 最 低 要 求 是 
OpenGL ES 2.0 以 及 Android 2.2。 这 现在 绝对 是 覆盖 面 很 广泛 了 一 Kivy 已 经 都 可 以 在 
Android 智能 手表 上 面 运 行 了 。 


当前 在 技术 上 存在 的 一 个 限制 就 是 Android 构建 工具 只 能 生成 ARM 平台 的 APK 文件 ， 这 些 
文件 不 能 运行 于 X86 处 理 器 的 Android 设备 上 ， 好 在 目前 这 类 X86 的 Android 设备 还 不 是 
主流 。 不 过 对 X86 处 理 器 的 Android 设备 的 支持 是 后 续 要 添加 的 。 


因为 目前 Kivy 基本 上 能 在 绝 大 多 数 Android 设备 上 面 良好 运行 了 ， 所 以 之 前 的 那个 设备 支持 
列表 就 关 荣 退休 了 一 只 要 满足 上 面 的 要 求 的 Android 设备 ， 基 本 就 都 能 够 使 用 。 


Title: Kivy Pack Android Date: 2017-03-06 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 41 6,7] Android 系统 可 
执行 文件 


你 可 以 通过 python-for-android 这 个 项 目 来 打包 一 个 Android 应 用 。 本 页 面 详细 讲解 如 何 下 载 
和 打包 ， 可 以 在 你 自己 的 机 器 上 直接 进行 (参考 此 页 Ba eee Ey 
Android 虚拟 机 ， 或 者 使 用 Buildozer 来 自动 化 完成 整个 过 程 。 还 可 以 参考 针对 Kivy 
Launcher 进行 打包 这 样 就 不 用 编译 就 能 运行 Kivy 应 用 。 


对 新 手 ，Kivy 官方 推荐 使 用 Buildozer ， 这 是 制作 完整 APK 的 最 简单 的 途径 。 或 者 也 可 以 使 
用 Kivy Launcher 这 个 应 用 来 运行 你 的 Kivy 应 用 ， 而 不 用 编译 了 。 


Kivy 应 用 可 以 发 布 到 Android 应 用 市 场 ， 比 如 谷歌 的 Play 市 场 等 等 ， 只 需要 额外 几 步 来 创建 
一 个 完整 签名 的 APK 就 可 以 了 。 


Kivy 项 目 包含 了 一 系列 读 取 Android API 的 工具 ， 可 以 实现 震动 、 传 感 器 读 取 、 信 息 发 送 等 
等 功能 。 相 关 的 详细 信息 都 可 以 参考 Kivy 的 Android 专题 页 面 
特别 注意 


Android 平台 目前 已 经 支持 Python 3 了 ， 不 过 还 处 于 实验 阶段 。 


Buildozeri 


Buildozer 是 一 个 将 整个 构建 过 程 自动 化 的 工具 。 它 会 下 载 和 设置 python for aridan 需要 的 
所 有 依赖 项 目 ， 包 括 Android 的 SDK 和 NDK， 然 后 会 构建 APK ， 这 个 APK 可 以 自动 推送 
到 设备 上 。 


目前 Buildozer 只 能 用 在 Linux 上 面 ， 而 且 还 不 是 正式 版 ， 处 于 测试 阶段 ， 发 布 的 是 alpha 版 
本 ， 不 过 目前 用 起 来 还 不 错 ， 能 显著 简化 APK 构建 的 过 程 。 


可 以 到 Buildozer 的 项 目 页 面 下 载 获取 Buildozer ° 


git clone https://github.com/kivy/buildozer.git 
cd buildozer 
sudo python2.7 setup.py install 


上 面 的 命令 就 会 把 Buildozer 安装 到 你 的 操作 系统 中 。 接 下 来 就 是 到 你 的 项 目 目录 然后 运行 如 
下 命令 


buildozer init 


会 在 你 的 目录 下 创建 一 个 名 为 buildozer.spec 的 文件 ， 这 个 文件 是 控制 项 目 构建 选项 的 。 
估计 你 需要 编辑 修改 一 下 这 个 文件 ， 比 如 设置 你 应 用 的 名 字 等 等 。 在 这 里 可 以 设置 传递 给 
python-for-android 的 全 部 或 者 大 部 分 参数 。 


安装 Buildozer 的 依赖 项 目 。 


最 后 一 步 了 ， 连 接 上 你 的 Android 设备 然后 运行 下 面 的 命令 : 


buildozer android debug deploy run 


这 样 就 可 以 创建 、 推 送 APK 到 你 的 设备 上 ， 然 后 就 可 以 自动 运行 了 。 


Buildozer 有 很 多 可 以 控制 的 选项 和 工具 ， 对 你 都 会 游泳 ， 上 面 这 些 步骤 只 是 创建 APK 的 最 
简单 的 方法 。 可 以 到 Buildozer 的 官方 文档 页 面 查 看 完整 说 明 。 也 可 以 看 看 Buildozer 项 目 页 
面 的 README 文件 。 


通过 python-for-android 打包 9 
你 还 可 以 直接 用 python-for-android 来 打包 应 用 ， 这 样 你 可 以 有 更 多 控制 选项 ， 但 需要 手动 下 
载 和 设置 Android 工具 链 。 


参考 python-for-android 官方 文档 查看 全 部 细节 。 


针对 Kivy Launcher 4T & f] 


Kivy launcher 是 一 个 Android 应 用 ， 可 以 运行 存储 到 SD 卡 里 面 的 Kivy 样 例 。 可 以 用 下 面 的 
方法 来 安装 Kivy launcher : 


1， 前 往 谷 歌 Play 市 场 中 的 Kivy Launcher 页 面 ; 
2. 点 击 安 5. X è 
3. "A pos ， 然 后 就 搞定 了 。 


如 果 你 的 设备 无 法 访问 谷歌 Play PH (我 大 天 朝 么 。。。) ， 可 以 从 Kivy 官网 的 下 载 页 面 
手动 下 载 安装 APK 文件 。 


安装 了 Kivy launcher 之 后 ， 就 可 以 把 你 的 Kivy 应 用 放 到 外 置 存储 的 Kivy 文件 夹 中 ， (通常 
是 在 /sdcard ARTF) ， 例 如 : 


/sdcard/kivy/yourapplication> 


<yourapplication> 14 5$ EJ] EL 3A — 4 XE ^ RSRVAT XT: 


t 程序 主 文件 : 

main.py 

# Kivy 需要 的 关于 你 应 用 的 信息 : 
android. txt 


以 下 信息 是 android.txt 这 个 文件 必须 包含 的 : 


title=<Application Title» # 这 是 应 用 的 标题 
author=<Your Name»  # 这 是 作者 笃 名 
orientation-«portrait|landscape» 4i 4e X RE A 





上 面 这 些 都 是 非常 基础 的 设置 。 如 果 你 要 用 上 面 的 工具 来 构建 自己 的 APK， 还 得 调整 很 多 其 
他 的 设 定 。 


zc ORBE PLUR ET 
Kivy 自 带 了 很 多 歌 样 例 ， 可 以 先 用 这 些 来 试 一 试 Kivy Launcher。 可 以 用 如 下 的 方法 来 运行 : 


下 载 Kivy demos for Android 

解压 缩 然后 进入 目录 kivydemo-for-android 

把 目录 内 所 有 子 目录 等 内 容 复制 到 /sdcard/kivy 这 个 目录 

运行 Kivy Launcher 然后 从 样 例 中 选择 一 个 来 试 试 ，Pictures, Showcase, Touchtracer, 
Cymunk 等 等 都 可 以 。 


^om 


A Ag $1 RI HY 


如 果 你 用 Buildozer 或 者 python-for-android 构建 了 APK 文件 ， 就 可 以 创建 一 个 release 版 本 
来 发 布 到 谷歌 Play 市 场 或 者 其 他 Android 应 用 市 场 。 


要 想 发 布 ? 就 必须 在 运行 Buildozer 的 时 候 添 加 上 release 参数 d 例如 buildozer android 
release ， 如 果 用 了 python-for-android 就 在 build.py 进行 编译 的 时 候 加 上 --release ° 


这 样 就 能 在 bin 目录 里 面 创建 一 个 正式 发 布 的 release 版 的 APK 文件 ， 需 要 你 做 好 签名 和 
zipalign 压缩 优化 〈 译 者 注 : zipalign， 优 化 apk 应 用 程序 的 工具 ， 使 包 内 未 压缩 的 数据 能 够 有 
序 的 排列 ) 。 


上 面 这 些 操 作 的 详细 过 程 可 以 参考 Android 官方 文档 ， 所 有 用 到 的 工具 都 在 Android SDK 里 
面 了 。 


1% 5% Android T 
Kivy 的 设计 定位 是 提供 跨 平 台 的 相同 操作 体验 ， 因 此 也 有 一 些 清 晰 地 设计 特点 。Kivy 包含 了 
自己 独 有 的 一 套 控件 ， 在 默认 情况 下 ， 用 所 有 需要 的 依赖 包 和 链接 库 来 构建 APK 文件 。 


也 可 以 指定 特定 的 Android 功能 ， 可 以 直接 进行 ， 也 可 以 用 (XE) 跨 平台 的 方式 来 实现 。 
更 多 细节 可 以 参考 Kivy 的 Android 专题 页 面 中 关于 使 用 Android API 的 部 分 。 


Title: Kivy VM Date: 2017-03-6 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : Kivy 虚拟 机 


ia] 4r 41 


目前 ，Kivy 的 Android 应 用 程序 构建 只 能 在 配置 有 python-for-android ^ Android SDK 和 
NDK 的 Linux 环境 进行 。 这 对 于 Windows 或 者 OS X 的 用 户 来 说 ， 搭 建 起 来 就 有 点 麻烦 ， 所 
以 Kivy 官方 提供 了 一 个 完全 配置 好 的 VirtualBox 虚拟 机 磁盘 镜像 ， 用 来 减轻 自己 搭建 的 说 伤 
与 痛苦 。 

如 果 你 对 于 虚拟 机 不 太 了 解 ， 建 议 去 阅读 以 下 维基 百科 上 面 的 虚拟 机 页 面 。 


xw 


1. 首先 是 到 Kivy FX 31 & 找到 Virtual Machine 这 一 部 分 。 下 载 的 文件 超过 2GB > HE 
缩 之 后 是 大 概 6GB。 解 压缩 文件 之 后 别 忘掉 vdi 虚拟 磁盘 的 位 置 。 

2. 根据 你 机 器 的 操作 系统 版 本 ， 去 VirtualBox 下 载 页 面 下 载 对 应 的 安装 包 ， 然 后 安装 。 

3. 启动 VirtualBox， 点 击 新 建 按钮 。 然 后 选择 操作 系统 为 “linux”， 版 本 设置 为 “Ubuntu 64- 
bit" » 

4. Æ “Hard drive” 硬盘 这 个 选项 ， 选 择 “Use an existing virtual hard drive file" > Pp4£ H LA 
的 虚拟 硬盘 文件 。 这 时 候 找 到 上 面 你 下 载 并 解压 出 来 的 那个 vdi 文件 ， 选 中 使 用 它 。 

5， 到 虚拟 机 设置 的 页 面 。 在 “Display -> Video" 显示器 -> 显卡 ， 这 一 部 分 ， 吧 显存 增加 到 至 
少 32MB 以 上 。 启 用 3D 加 速 来 提高 用 户 体验 。 

6. 启动 虚拟 机 ， 然 后 看 看 桌面 上 的 readme 文件 ， 根 据 指 示 操 作 就 行 了 。 


构建 APKT 
虚拟 机 家 在 之 后 ， 就 根据 python-for-android 打包 指南 里 面 的 讲解 来 构建 APK 文件 里 了 : X 


文 原版 ， 中 文 翻译 版 本 或 者 知 乎 专栏 的 镜像 。 也 根本 不 用 使 用 git clone 下 载 什么 的 了 ， 因 为 
虚拟 机 里 面 的 python-for-android 已 经 安装 配置 好 了 ， 就 在 虚拟 系统 的 home 目录 里 面 了 。 


提示 建议 四 


1. 共享 文件 夹 通常 情况 下 ， 你 的 开发 环境 和 工具 链 都 在 宿主 机 中 ， 而 APK 的 构建 在 客户 机 


里 面 。 好 在 VirtualBox 提供 了 共享 文件 夹 的 功能 ， 允 许 你 的 客户 机 直接 读 取 宿主 机 中 的 
某 个 文件 夹 。 可 以 选中 ‘Permanent (永久 挂 载 ) 和 ‘Auto-mount’ (自动 挂 载 ) 这 两 个 选 
项 ， 这 样 把 构建 好 的 APK 文件 复制 到 宿主 机 就 更 方便 了 。 写 一 个 小 脚本 就 可 以 很 简单 地 
实现 自动 复制 或 者 移动 这 个 步骤 。 

. 复制 粘贴 默认 情况 下 ， 和 宿主 机 和 客户 机 的 剪贴 板 是 不 能 共享 的 。 可 以 在 “Settings -> 
General -> Advanced" (设置 -> 通用 -> 高 级 ) 中 局 用 “bi-directional”〈 双 向 复制 粘贴 ) 的 
选项 。 

.虚拟 机 快照 如 果 你 正在 用 Kivy 开发 环境 的 分 支 ， 同步 最 新 版 本 有 时 候 可 能 会 出 问题 
(Kivy 开发 者 尽量 在 避免 这 种 情况 ) 。 所 以 可 以 在 更 新 之 前 建立 一 个 虚拟 机 快照 来 避免 
这 类 问题 。 这 能 让 你 很 方便 恢复 到 之 前 能 用 的 状态 。 

.补充 内 存 如 果 上 庶 拟 机 分 配 的 内 存 不 够 ， 可 能 会 因为 一 些 很 神奇 的 错误 导致 编译 失败 ， 比 
如 : 


arm-linux-androideabi-gcc: Internal error: Killed (program cci) 


如 果 出 现 了 上 面 这 种 情况 ， 检 查 一 下 Kivy 座 拟 机 的 剩余 内 存 ， 如 果 内 存 不 足 ， 就 在 虚拟 
机 设置 里 面 多 增加 一 些 吧 。 


Title: Kivy Pack Mac Date: 2017-03-02 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 打包 为 Mac 系统 可 执行 
文件 


特别 注意 


本 文 所 提供 的 打包 Kivy 应 用 程序 的 方法 必须 在 OS X 系统 内 进行 ， 而 且 不 再 支持 32 位 平 


So 


使 用 Buildozer 


pip install git+http://github.com/kivy/buildozer cd /to/where/I/Want/to/package buildo 
zer init 
( 译 者 注 : 这 里 的 /to/where/l/Want/to/package 就 是 你 要 打包 的 应 用 所 在 目录 。) 


然后 就 还 是 修改 buildozer.spec 文件 ， 在 里 面 添加 好 你 的 应 用 需要 用 到 的 信息 。 添 加 依赖 包 
的 位 置 在 requirements= 的 那个 位 置 。 


默认 情况 下 ，requirements 位 置 所 指定 的 Kivy 版 本 会 被 忽略 掉 。 


如 果 你 在 应 用 程序 目录 下 有 Kivy.app (/Applications/Kivy.app) ， 那 就 会 用 这 个 来 打包 。 如 
果 没 有 ， 还 可 以 从 Kivy.org 下 载 最 新 版 来 用 了 。 


如 果 你 要 用 Python3 来 打包 ， 就 就 直接 从 Kivy.org 的 下 载 页 面 下 载 Kivy3.7z 这 个 包 ， 然 后 把 
它 解 压缩 到 应 用 目录 [Applications 下 ， 命 名 为 Kivy.app， 然 后 运行 : 


buildozer osx debug 


打包 好 应 用 之 后 ， 就 可 以 移 除 用 不 上 的 包 了 ， 比 如 如 果 你 不 用 视频 功能 ， 那 就 可 以 去 挤 
gstreamer。 同 理 ， 其 他 的 用 不 上 的 功能 ， 也 都 可 以 去 掉 ， 这 就 可 以 保证 打包 出 来 的 应 用 能 够 
有 尽量 小 的 体积 ， 足 够 运行 就 好 了 。 


作为 示例 ， 我 们 用 这 个 方法 打包 好 了 一 个 应 用 ，Python2 的 版 本 大 概 9MB 多 一 点 ，Python3 
的 是 15MB 左右 ， 可 以 在 官方 提供 的 谷歌 网 瘟 下 载 来 体验 一 下 。 ( 译 者 注 : 如 果 你 身 处 大 陆 
而 无 法 访问 谷歌 这 种 不 存在 的 网 站 ， 那 么 可 以 试 试 我 的 百度 网 盘 分 享 。) 


就 这 么 多 ， 动 手 试 试 吧 。 


目前 的 Buildozer 使 用 了 Kivy SDK 来 打包 你 的 应 用 程序 。 如 果 你 想 对 你 的 程序 进行 更 深入 的 
修改 定制 ， 而 buildozer 不 足以 满足 你 的 需求 ， 你 可 以 试 试 直接 使 用 SDK， 下 面 就 要 详细 介 


绍 一 下 这 部 分 。 


使 用 Kivy SDK 


从 1.9.0 版 本 开始 ，Kivy 就 开始 发 布 针 对 OS X 平台 的 自我 包含 的 便捷 包 。 


用 下 面 描述 的 方法 就 可 以 使 用 Kivy SDK 来 打包 和 发 布 应 用 程序 了 ， 要 添加 一 些 诸如 SDL2 或 
者 GStreamer 之 类 的 包 也 都 更 简单 了 。 


1 首先 要 确保 有 未 修改 过 的 原版 Kivy SDK， 也 就 是 从 下 载 页 面 获取 的 Kivy.app 这 个 文件 。 


2 然后 运行 下 面 的 命令 : 


mkdir packaging 

cd packaging 

packaging» git clone https://github.com/kivy/kivy-sdk-packager 
packaging> cd kivy-sdk-packager/osx 

osx> cp -a /Applications/Kivy.app ./Kivy.App 


特别 注意 


上 面 这 一 步 是 至 关 重 要 的 ， 一 定 要 确保 目录 和 权限 都 没有 问题 。 cp -rf 这 样 的 命令 也 能 实现 
复制 ， 但 会 让 应 用 程序 无 法 运行 ， 并 且 在 后 续 步 又 中 导致 各 种 错误 。 


3 接 下 来 就 是 要 把 你 用 Kivy.app 编译 好 的 应 用 程序 包含 进 目标 文件 夹 ， 使 用 如 下 命令 : 


osx> ./package-app.sh /path/to/your/app_folder_name>/ 


就 是 你 应 用 程序 的 名 字 。 

这 个 命令 会 把 Kivy.app 复制 成 .app， 并 把 应 用 程序 的 一 份 编译 好 的 副本 包含 进去 。 

4 就 这 些 了 ， 你 的 应 用 程序 已 经 打包 完毕 ， 可 以 拿 出 去 安装 了 。 接 下 来 可 以 按照 下 面 的 方法 对 
你 的 应 用 进行 更 进一步 的 定制 了 。 

安装 模块 


OS X 上 的 Kivy 包 邮 自己 的 虚拟 环境 ， 当 你 使 用 kivy 命令 来 运行 的 时 候 就 会 激活 这 个 虚拟 环 
境 。 如 果 要 安装 额外 的 一 些 模块 ， 可 以 用 如 下 命令 : 


kivy -m pip install 


模块 和 文件 安 到 哪 了 ? 
在 Kivy.app 这 个 文件 内 部 ， 庶 拟 环境 位 置 如 下 : 
Kivy.app/Contents/Resources/venv/ 
如 果 你 安装 了 一 个 安装 二 进 制 的 模块 ， 比 如 kivy-garden。 那 么 这 些 二 进 制 文件 只 能 在 虚拟 环 
境 中 才 是 可 用 的 ， 就 比如 你 先 运行 了 下 面 这 个 命令 : 


kivy -m pip install kivy-garden 


然后 安装 的 garden lib 就 只 在 你 激活 这 个 虚拟 环境 的 时 候 才 可 用 。 


source /Applications/Kivy.app/Contents/Resources/venv/bin/activate garden install mapv 
iew deactivate 


安装 二 进 制 文件 


这 个 比较 简单 ， 就 把 二 进 制 文件 复制 到 虚拟 目录 下 的 bin 文件 夹 就 可 以 了 。 
( Kivy.app/Contents/Resources/venv/bin/ ) 


包含 其 他 框架 


Kivy.app 已 经 自 带 了 SDL2 和 Gstreamer 这 两 个 框架 。 要 和 包含 其 他 框架 可 以 参考 下 面 的 方 
ei 


git clone http://github.com/tito/osxrelocator 

export PYTHONPATH--/path/to/osxrelocator 

cd Kivy.app 

python -m osxrelocator -r . /Library/Frameworks/<Framework_name>.framework/ \ 
Qexecutable path/../Frameworks/«Framework name».framework/ 


Do not forget to replace with your framework. This tool osxrelocator essentially changes the 
path for the libs in the framework such that they are relative to the executable within the 
.app, making the Framework portable with the .app. 


一 定 别 总 了 把 上 面 样 例 中 的 替换 成 你 要 安装 的 框架 名 字 。osxrelocator 这 个 工具 可 以 改变 杠 
架 中 的 链接 库 的 路 径 ， 这 样 就 能 让 它们 指向 .app 文件 内 的 可 执行 文件 ， 也 就 让 此 框架 成 为 
app 文件 内 可 用 的 内 置 框架 了 。 


缩小 应 用 体积 
现在 这 个 应 用 程序 的 体积 可 能 已 经 相当 大 了 ， 好 在 很 多 没有 用 上 的 部 分 可 以 从 包 中 移 除 。 


举例 来 说 ， 如 果 你 没有 使 用 Gstreamer， 就 可 以 从 你 应 用 程序 的 .app 文件 内 的 
/Contents/Frameworks 目录 中 把 它 删 除 掉 。 类 似 的 像 是 在 
/Applications/Kivy.app/Contents/Resources/kivy/ 目录 下 的 examples，tools，docs 等 等 这 
文件 夹 都 可 以 删 掉 的 。 


这 样 就 可 以 让 你 的 包 只 和 包含 你 的 应 用 程序 用 到 的 内 容 。 


修改 设 


FÉ. 


通过 修改 应 用 程序 的 .app 文件 内 /Contents/info.plist 这 个 文件 ， 就 可 以 修改 图 标 和 其 他 的 设 
了 


o 


创建 DMG 
用 如 下 命令 就 可 以 创建 一 个 DMG 镜像 文件 了 : 


osx> ./create-osx-dmg.sh YourApp.app 


一 定 要 注意 末尾 没有 额外 的 /。 这样 就 能 生成 一 个 压缩 的 DMG 文件 ， 能 进一步 缩小 应 用 发 布 
时 候 的 体积 了 。 


使 用 PyInstaller * 无 HomeBrew 


首先 是 安装 Kivy 和 依赖 包 ， 不 用 HomeBrew 的 方法 可 以 在 官方 文档 或 者 译 者 的 博客 或 者 译 
者 的 专栏 中 查找 。 

安装 好 了 Kivy 以 及 依赖 包 之 后 ， 就 需要 安装 Pylnstaller 了 。 

( 译 者 注 : Pylnstaller 目前 不 支持 Python3.6， 时 间 为 2017-03-02。) 


假设 用 一 个 名 为 testpackaging 的 文件 夹 : 


cd testpackaging 
git clone http://github.com/pyinstaller/pyinstaller 


在 这 个 目录 中 创建 一 个 名 为 touchtracer.spec 的 配置 文件 ， 然 后 添加 如 下 的 代码 到 该 文件 中 : 


# -*- mode: python -*- 


block_cipher = None 
from kivy.tools.packaging.pyinstaller_hooks import get_deps_all, hookspath, runtime_ho 
oks 


a = Analysis(['/path/to/yout/folder/containing/examples/demo/touchtracer/main.py'], 
pathex=['/path/to/yout/folder/containing/testpackaging'], 
binaries=None, 
win_no_prefer_redirects=False, 
win_private_assemblies=False, 
cipher=block_cipher, 
hookspath=hookspath(), 
runtime_hooks=runtime_hooks(), 

**get_deps_all()) 

pyz = PYZ(a.pure, a.zipped_data, 
cipher=block_cipher ) 

exe = EXE(pyz, 

a.scripts, 
exclude_binaries=True, 
name='touchtracer', 
debug=False, 
strip=False, 
upx=True, 
console=False ) 
coll = COLLECT(exe, Tree('../kivy/examples/demo/touchtracer/'), 
Tree('/Library/Frameworks/SDL2 ttf.framework/Versions/A/Frameworks/Free 
Type.framework'), 
a.binaries, 
a.zipfiles, 
a.datas, 
strip-False, 
upx-True, 
name-'touchtracer') 

app = BUNDLE(coll, 
name='touchtracer.app', 
icon=None, 

bundle_identifier=None) 


把 路 径 改 到 你 的 相对 路 径 : 


a = Analysis(['/path/to/yout/folder/containing/examples/demo/touchtracer/main.py'], 
pathex=['/path/to/yout/folder/containing/testpackaging'], 


coll = COLLECT(exe, Tree('../kivy/examples/demo/touchtracer/'), 


pyinstaller/pyinstaller.py touchtracer.spec 


把 这 里 的 touchtracer 替换 成 你 的 应 用 名 称 。 之 后 就 可 以 在 dist 文件 夹 下 看 到 你 的 app 文件 
了 。 


使 用 Pylnstaller + HomeBrew 
特别 注意 
打包 你 的 应 用 程序 的 时 候 ， 你 定 要 在 你 要 兼容 的 最 老 版 本 的 OS X 系统 上 进行 。 


完整 指南 


安装 Homebrew 


-— 


E: 


2 安装 Python: 


brew install python 


特别 注意 


如 果 要 用 Python3 ， 就 用 brew install pythons ， 然 后 把 下 文中 的 pip AA pips 就 可 以 
Ta 


3 (Re)install your dependencies with --build-bottle to make sure they can be used on 
other machines: 


brew reinstall --build-bottle sdl2 sdl2 image sdl2 ttf sdl2 mixer 


特别 注意 
如 果 你 的 项 目 依赖 Gstreamer 或 者 其 他 的 链接 库 ， 一 定 要 按照 下 文 的 方法 添加 --build- 


iz 3 


bottle 来 安装 2 


d 


4 安装 Cython 和 Kivy: 


pip install -I Cython==0.23 
USE_OSX_FRAMEWORKS=0 pip install -U kivy 


d 


5 安装 Pylnstaller: 


pip install -U pyinstaller 


6 使 用 到 main.py 的 路 径 来 打包 应 用 : 


pyinstaller -y --clean --windowed --name touchtracer \ 
--exclude-module _tkinter \ 
--exclude-module Tkinter \ 
--exclude-module enchant \ 
--exclude-module twisted \ 
/usr/local/share/kivy -examples/demo/touchtracer/main. py 


这 样 不 能 把 额外 的 图 像 和 声音 文件 复制 进去 。 要 添加 这 些 内 容 还 是 要 创建 一 个 专门 的 ` .spec ` 配 置 文件 。 


咱们 用 的 这 个 配置 文件 是 touchtracer.spec > 位 置 在 刚刚 运行 了 pyinstaller 的 目录 。 


需要 对 配置 文件 中 的 COLLECT() 调用 的 部 分 进行 修改 ， 要 添加 上 touchtracer 用 到 的 资源 (比如 touchtrace 
r.kv， particle.png> 等 等 )。 修 改 这 一 行 ， 添 加 一 个 Tree() 对 象 。 这 个 Tree 会 搜索 touchtracer A 
录 下 的 所 有 文件 ， 并 添加 到 你 的 包 当 中 。 COLLECT 的 那 部 分 代码 应 该 大 概 如 下 所 示 : 


`` ` Bash 
coll = COLLECT(exe, Tree('/usr/local/share/kivy-examples/demo/touchtracer/'), 
a.binaries, 
a.zipfiles, 
a.datas, 
strip=None, 
upx=True, 
name-'touchtracer') 


这 样 会 把 需要 的 文件 都 添加 进去 ， 这 样 Pylnstaller 就 能 包含 需要 用 到 的 Kivy LAT o FET 
， 你 的 spec 配置 文件 就 可 以 执行 了 。 


使 用 spec 来 构建 并 打包 成 DMG 
1 打开 终端 。 


2 进入 到 Pylnstaller 的 目录 ， 然 后 用 如 下 命令 进行 构建 : 


pyinstaller -y --clean --windowed touchtracer.spec 


3 运行 来 试 试 : 


pushd dist 
hdiutil create ./Touchtracer.dmg -srcfolder touchtracer.app -ov 
popd 


4 然后 就 能 在 dist 目录 下 找到 Touchtracer.dmg 这 个 文件 了 。 
额外 的 链接 库 

GStreamer 

如 果 你 的 项 目 需 要 GStreamer， 那 就 运行 如 下 命令 : 


brew reinstall --build-bottle gstreamer gst-plugins-{base, good, bad, ugly} 


特别 注意 


如 果 你 的 项 目 需要 对 Ogg Vorbis (音频 压缩 格式 ， 类 似 于 MP3， 完 全 免费 、 开 放 和 没有 专利 
限制 ， 支 持 多 声 道 ) 的 支持 ， 一 定 要 在 上 面 的 命令 后 加 上 --with-libvorbis ° 


如 果 你 用 的 是 通过 HomeBrew 安装 的 Python， 那 就 还 需要 下 面 这 一 步 ， 除 非 这 个 问题 再 受 
f: 


brew reinstall --with-python --build-bottle https://github.com/cbenhagen/homebrew/raw/ 
patch-3/Library/Formula/gst-python.rb 


Title: Kivy Pack iOS Date: 2017-03-07 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 打包 为 IOS 系统 可 执行 文 
Hr 


The overall process for creating a package for IOS can be explained in 4 steps: 


总 体 上 创建 一 个 iOS 应 用 程序 需要 四 步 : 〈 译 者 注 : 对 ， 你 没有 看 错 ， 官 方 文档 就 是 写 的 4 
steps， 所 以 我 特地 留 下 了 上 面 这 行 原文 ， 可 见 估计 Kivy 的 开发 者 们 也 没 太 注 意 这 点 小 错误 
"Hoo o ) 

针对 iOS 编译 Python 和 需要 的 模块 ; 


1. 
2. 创建 一 个 Xcode 项 目 ， 链 接 你 的 源 代 码 ; 
3. 进行 定制 修改 。 
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brew install autoconf automake libtool pkg-config 
brew link libtool 

sudo easy_install pip 

sudo pip install cython==0.23 


更 多 细节 参考 IOS Prerequisites。 一 定 要 在 下 一 步 开 始 之 前 保证 依赖 关系 都 满足 了 。 


编译 发 布 版 外 
Open a terminal, and type: 


打开 终端 ， 输 入 下 面 的 命令 : 


git clone git://github.com/kivy/kivy-ios 
cd kivy-ios 
./toolchain.py build kivy 


Python 发 型 版 中 大 部 分 内 容 都 会 被 打包 到 python27.zip 这 个 文件 中 。 如 果 遇 到 了 问题 ， 可 以 
参考 谷歌 论坛 用 户 组 或 者 kivy-ios 项 目 页 面 。 
创建 一 个 Xcode RAY 


在 进行 下 一 步 之 前 ， 要 保证 你 的 程序 运行 起 点 是 一 个 名 为 main.py 的 文件 。 


Kivy 官方 提供 了 一 个 脚本 ， 可 以 创建 一 个 初始 的 Xcode 项 目 。 在 下 面 的 代码 样 例 中 ， 把 
Touchtracer 这 个 换 成 你 的 项 目 名 字 。 名 字 一 定 不 能 有 空格 或 者 其 他 非法 字符 。 ( 译 者 注 : 吐 
槽 一 下 ， 那 什么 算是 非法 字符 倒是 说 说 啊 。 ) 


./toolchain.py create <title> <app_directory> 
./toolchain.py create Touchtracer ~/code/kivy/examples/demo/touchtracer 


特别 注意 
上 面 这 一 步 中 ， 应 用 程序 的 路 径 一 定 要 用 完整 路 径 。 


接 下 来 会 有 一 个 名 字 为 <title> -ios 的 目录 被 创建 ， 里 面 就 是 Xcode 项 目 了 。 可 以 打开 这 个 
项 目 : 


open touchtracer-ios/touchtracer .xcodeproj 
后 点 击 Play 运行 ， 就 可 以 了 。 


特别 注意 


每 次 点 击 Play 的 时 候 ， 你 的 应 用 目录 都 会 同步 到 <title> -ios/YourApp 这 个 目录 。 不 要 直接 
对 这 个 目录 进行 修改 。 


更 新 Xcode 73 E project] 


举 个 例子 ， 加 入 你 要 在 你 的 项 目 中 添加 numpy， 但 在 之 前 创建 这 个 Xcode 项 目的 时 候 没有 编 
译 进 去 。 那 首先 就 构建 numpy : 


./toolchain.py build numpy 


然后 更 新 一 下 你 的 Xcode MA : 


./toolchain.py update touchtracer-ios 


这 样 所 有 相关 的 链接 库 、 框 架 就 都 被 添加 到 你 的 Xcode 项 目 里 去 了 。 


定制 修改 四 


有 很 多 方法 能 对 你 的 应 用 进行 修改 和 设置 。 可 以 参考 kivy-ios 的 文档 来 查看 更 详细 的 信 ， 


已 知 的 问题 四 


目前 关于 iOS 打包 的 所 有 已 知 问题 都 可 以 在 Kivy-iOS 的 GitHub issues 页 面 查看 到 。 如 果 你 
遇 到 的 问题 不 在 其 中 ， 请 创建 一 个 新 的 issue * Kivy 开发 者 会 尽快 跟 进 处 理 。 


已 知 的 问题 中 绝 大 部 分 都 太 技 术 性 了 ， 没 必要 在 这 里 写 了 ， 其 中 一 个 重要 的 问题 是 目前 没 办 
法 移 除 一 些 链接 库 (比如 SDL Mixer) > AA oe 项 目 需要 这 些 链接 库 。 在 后 续 的 版 本 中 ， 
Kivy 开发 者 会 解决 掉 这 些 问题 。 


FAQT 
程序 异常 退出 


默认 情况 下 ， 所 有 控制 台 和 文件 中 的 print 语句 都 被 忽视 了 。 如 果 你 运行 程序 的 时 候 碰 到 异常 
状况 了 ， 可 以 激活 log 日 志 功 能 ， 在 main.m 文件 中 把 下 面 这 一 行 去 掉 注释 : 


putenv("KIVY_NO_CONSOLELOG=1") ; 
然后 你 就 可 以 在 Xcode 控制 台中 看 到 Kivy 的 日 志 了 。 


渣 果 公司 怎样 才能 接受 一 个 Python APP?T 


Kivy 开发 者 将 所 有 链接 库 的 app 二 进 制 文 件 合并 成 了 一 个 名 为 libpython 的 二 进 制 文件 。 这 
就 意味 着 所 有 二 进 制 模块 都 会 提前 价值 ， 所 以 不 会 有 动态 加 载 。 


是 否 已 经 向 渣 果 的 App store 提交 过 Kivy 应 用 ?9 


iOS 打包 


是 ， 例 如 下 面 的 就 是 : 


e Defletouch on iTunes， 
e ProcessCraft on iTunes 


更 详细 的 列表 可 以 参考 Kivy wiki. 
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Title: Kivy Pack License Date: 2017-03-07 Category: Kivy Tags: Python,Kivy 


Kivy 中 文 编程 指南 : 授权 协议 


这 并 不 是 一 个 律师 咨询 指南 | Kivy 的 开发 组 织 ， 本 指南 的 作者 以 及 参与 者 ， 对 任何 信息 缺 
失 、 产 生 误 导 ， 以 及 任何 基于 这 份 指南 的 行为 产生 的 任何 后 果 都 不 负 任何 责任 。 这 个 指南 只 
是 提供 一 些 信息 ， 目 的 是 帮助 缺乏 经 验 的 用 户 。 


你 的 代码 本 身 并 不 一 定 需要 包括 协议 信息 和 对 其 他 用 到 的 软件 的 版 权 声 明 ， 不 过 二 进 制 文件 
就 不 一 样 了 。 


当 你 创建 一 个 二 进 制 文件 (比如 exe * app 或 者 APK 等 等 ) 的 时 候 ， 里 面包 括 了 Kivy 以 及 其 
他 的 一 些 依赖 项 目 或 者 你 的 应 用 程序 用 到 的 其 他 的 包 ， 其 中 的 某 些 就 可 能 有 声明 需要 你 再 自 
己 的 应 用 程序 中 进行 版 权 信息 声明 。 在 你 对 这 些 二 进 制 文件 进行 发 布 之 前 ， 一 定 要 检查 所 有 
不 属于 你 源 代码 的 创建 出 来 的 文件 ， (比如 dll * pyd > so 等 等 ) 然后 如 果 某 一 个 文件 需要 有 
版 权 信 息 ， 记 得 加 进去 版 权 声 明 。 这 样 你 才能 满足 Kivy 开发 需要 的 版 权 要 求 。 


R eLa 


在 Kivy 支持 的 每 个 平台 上 都 或 多 或 少 地 用 到 了 下 面 这 些 依赖 包 ， 所 以 你 需要 添加 这 些 授 权 协 
议 进 去 ， 基 本 都 是 只 要 你 粘贴 一 段 版 权 声 明 到 你 的 应 用 中 ， 而 不 能 当 作 自己 写 了 这 些 功能 代 
49 o 


e docutils 

e pygments 

e sdl2 

e glew 

e gstreamer (如 果 用 到 了 再 添加 ) 
e 图 像 和 音频 库 ( 例 如 SDL_mixen) 


对 于 图 像 和 音频 库 ， 可 能 需要 你 手动 去 检查 一 下 ， 一 般 都 是 以 lib 这 三 个 字母 开头 的 。 这 些 
程序 的 LICENSE* 授权 协议 文件 会 在 Pylnstaller 里 面包 含 ， 但 在 python-for-android 则 没 
有 ， 所 以 你 得 自己 查找 一 下 。 


Windows 操作 系统 (PylInstaller)] 


要 使 用 Windows API 功能 ，Kivy 使 用 了 pypiwin32 。 这 个 包 是 基于 PSF 协议 发 布 的 。 


VS TARTA 


使 用 Visual Studio 编译 的 Python (官方 版 本 ) 使 用 了 来 自 微软 的 一 些 文件 ， 在 特定 条 件 下 基 
于 CRT license 可 以 重新 发 布 这 些 组 件 。 和 包括 这 些 文件 名 以 及 Py2 CRT 协议 或 者 Py3 CRT 
协议 ， 主 要 看 你 用 的 是 哪个 版 本 的 解释 器 ， 所 以 要 针对 你 的 发 布 对 象 来 具体 情况 具体 对 待 。 


e 可 再 发 行 组 件 列表 .aspXI) 


其 他 链接 库 引 


e zlib 


特别 注意 


对 那些 没有 直接 使 用 ， 但 是 打包 的 时 候 用 到 的 包 要 列 出 ， 比 如 在 Windows 系统 上 面 用 的 
Pylnstaller ° 


Linux 


GNU/Linux 操作 系统 现在 有 好 多 发 行 版 ， 所 以 没有 一 个 能 够 通用 给 所 有 发 行 版 的 指南 。 这 部 
分 也 属于 RPi (不 知道 是 什么 鬼 东 西 ) 。 然 而 可 以 简化 成 两 种 打包 方式 ， (还 是 用 
Pylnstaller 来 打包 ) 提供 包含 的 二 进 制 文件 ， 或 者 不 提供 。 


如 果 和 包含 了 二 进 制 文件 ， 应 该 逐个 检查 这 些 文件 ， 比 如 so 为 扩展 名 的 ， 除 了 你 的 代码 之 外 ， 
要 找到 对 应 这 些 文件 的 授权 协议 。 根 据 这 个 协议 你 可 能 需要 在 你 的 程序 里 面 添 加 一 条 对 应 的 
版 权 信 息 心 ° 


如 果 没 有 包含 二 进 制 文件 ， 比 如 你 用 deb 等 格式 的 文件 进行 打包 ， 那 就 把 矿 烦 扔 给 你 的 用 户 
了 。 你 可 以 自己 决定 是 否 要 满足 其 他 授权 的 要 求 ， 例 如 在 你 的 应 用 中 是 否 添 加 额外 的 版 权 信 
B. o 


AN 


Android{ 
APK 实际 上 只 是 一 个 文件 压缩 包 ， 所 以 可 以 解压 缩 这 个 文件 (就 像 Windows 里 面 那样 做 ) 然 
后 检查 每 个 文件 。 


APK/assets/private.mp3/private.mp3/ 这 个 文件 夹 内 有 所 有 和 包 含 的 文件 。 大 多 数 的 都 是 和 Kivy 
* Python 或 者 你 的 代码 相关 的 ， 不 过 那些 与 这 些 无 关 的 就 需要 检查 一 下 了 。 


已 知 的 包 


e pygame (如 果 用 了 昌 的 工具 链 ) 
e sqlite3 
e six 


有 的 包含 的 链接 库 是 Kivy 直接 使 用 或 者 通过 Pygame/SDL2 来 使 用 的 ， 他 们 的 位 置 在 
APK/lib/armeabi/ 。 大 多 数 都 是 和 依赖 包 相 关 ， 要 么 就 是 由 python-for-android 产生 ， 并 且 可 
能 就 是 python-for-android 的 一 部 分 。 例 如 libapplication.so 等 。 


Mac1| 


Missing. 这 部 分 Kivy 官方 文档 没 写 其 他 内 容 。 


iOS] 


Missing. 这 部 分 Kivy 官方 文档 没 写 其 他 内 容 。 


避免 二 进 制 文件 由 


有 一 种 方法 也 许 能 够 避免 这 种 很 狗 很 麻烦 的 授权 协议 什么 的 鬼 东 西 ， 就 是 不 用 任何 第 三 方 的 
鬼 扯 玩意 来 构建 你 的 应 用 。 你 可 以 用 Python 来 自己 创立 一 个 模块 ， 在 其 中 的 _main .py 都 
只 有 你 自己 的 代码 ， 而 setup.py 列 出 需要 的 依赖 包 


这 样 你 依然 可 以 发 布 你 的 应 用 一 就 是 你 的 代码 ， 然 后 你 就 不 用 管 任何 其 他 的 授权 协议 了 。 不 

过 这 样 就 更 像 是 搭配 使 用 ， 而 不 太 算是 发 布 程序 了 。 这 时 候 满 足 各 种 授权 的 依赖 关系 ， 就 转 
移 到 你 的 程序 的 用 户 身上 了 ， 他 们 需要 自行 搞定 运行 环境 来 使 用 这 个 模块 。 如 果 你 比较 关心 
自己 的 用 户 ， 建 议 你 还 是 花 点 时 间 来 阅读 一 下 可 能 导致 的 后 果 。 


Title: Kivy-Desinger on Mac ImportError: No module named filebrowser Date: 2016-12-31 
Category: Kivy Tags: Python,Mac,Kivy 


ft 3: Mac & 2% .EKivy-Desinger A Garden X 1 E 
不 匹配 导致 的 filebrowser 无 法 导入 的 问题 


根据 官方 文档 ， 首 先 要 


kivy -m pip install -U watchdog pygments docutils jedi gitpython six kivy-garden 


garden install filebrowser 


然后 你 以 为 一 切 都 很 好 ， 尝 试 运 行 Kivy-Designer， 你 会 遇 到 类 似 下 面 的 错误 提示 


[WARNING ] stderr: from designer.app import DesignerApp 

[WARNING ] stderr: File "/Users/cycleuser/kivy-designer/designer/app.py", 
line 27, in <module> 

[WARNING ] stderr: from kivy.garden.filebrowser import FileBrowser 
[WARNING ] stderr: ImportError: No module named filebrowser 


这 是 因为 ，garden 在 Mac OS XF x # 4912 @ x Linux F 4 ~/.kivy/garden 目录 下 ， 而 在 Mac 
OS X 下 这 个 位 置 是 无 效 的 ， 必 须要 手动 复制 到 
/Applications/Kivy.app/Contents/Resources/.kivy/garden 目录 下 。 


读 到 这 里 你 应 该 就 能 解决 问题 了 ， 仔 细 阅 读 官方 文档 ， 虽 然 在 garden 安 装 位 置 这 个 bug 上 并 没 
什么 


下 面 的 内 容 是 我 在 去 年 时 候 无 脑 尝试 的 记录 ， 仅 仅 作为 教训 有 参考 意义 而 已 ， 不 要 像 我 一 样 
e 分 割 线 下 面 的 内 容 就 不 用 看 了 ， 没 什么 意义 ~ 


At first, | ran the commands below to install Kivy on my Mac: 


Z ha ge C Hm Ay 字 n? so ay 4 He HE SP F Tod c 
最 开始 是 安装 依赖 包 ， 我 用 的 是 brew， 官 方 这 么 推荐 就 这 么 用 了 哈 : 


brew install sdl2 sdl2 image sdl2 ttf sdl2 mixer gstreamer 
pip install -I Cython--0.21.2 
USE OSX FRAMEWORKS-0 pip install git+https://github.com/kivy/kivy.git@1.9.0 


After that, | download the Kivy dmg from the official website. 


然后 呢 ， 就 去 官网 下 载 最 新 的 那个 kivy 的 dmg， 这 个 是 用 来 在 Mac 上 面 建立 一 个 Kivy 
官方 给 打包 好 的 Python 虚拟 环境 ， 就 不 用 自己 折腾 了 。 最 下 面 哪 句点 击 MakeSymlinks 
就 是 用 来 建立 系统 映射 的 一 个 脚本 ， 到 时 候 在 终端 直接 输入 kivy 就 是 运行 的 kivy.app 内 
部 的 一 个 Python2.7 了 ， 而 不 用 自己 折腾 配置 了 。 你 看 这 一 名 英文 我 翻译 解释 出 这 么 多 ， 
是 因为 我 觉得 身边 的 小 白 变 多 ， 解 释 清楚 点 比较 好 。 (虽然 英文 版 的 也 是 我 写 的 ， 但 我 
懒得 写 的 那么 细 ， 网 上 英语 资料 很 多 ， 就 让 他 们 自己 搜 去 吧 。。。) 


Download the latest version from http://kivy.org/#download 
Double-click to open it 

Drag the Kivy.app into your Applications folder 

Double click the makesymlinks script. 


Then | used git to download the kivy-designer. | thought it would work. So | typed in the 
command below following the official guide with hope: 


接着 就 用 git 下 载 来 kivy-designer。 满心 开心 希望 能 用 了 。 所 以 就 根据 官方 指南 输入 下 
面 的 命令 ， 满眼 星星 的 期 待 呢 : 


kivy main.py 


But | got this error: 


尼 玛 给 老子 来 了 个 错误 : 
[WARNING ] stderr: ImportError: No module named filebrowser 
Details here: 


细节 是 这 样 的 : 


[INFO ] Logger: Record log in /Applications/Kivy.app/Contents/Resources/. 
kivy/logs/kivy_15-12-29 18.txt 


[INFO ] Kivy: v1.9.0 

[INFO ] Python: v2.7.10 (default, Jul 14 2015, 19:46:27) 

[GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.39)] 

[INFO ] Image: Providers: img tex, img imageio, img dds, img gif, img sdl 


2 (img pil, img ffpyplayer ignored) 


[INFO ] Factory: 173 symbols loaded 

[INFO ] Text: Provider: sdl2 

[INFO ] OSC: using <multiprocessing> for socket 

[INFO ] Window: Provider: sdl2 

[INFO ] GL: OpenGL version «2.1 INTEL-10.6.33> 

[INFO ] GL: OpenGL vendor «Intel Inc.» 

[INFO ] GL: OpenGL renderer «Intel HD Graphics 4000 OpenGL Engine» 
[INFO ] GL: OpenGL parsed version: 2, 1 

[INFO ] GL: Shading version «1.20» 

[INFO ] GL: Texture max size «16384» 

[INFO ] GL: Texture max units «16» 

[INFO ] Window: auto add sdl2 input provider 

[INFO ] Window: virtual keyboard not allowed, single mode, not docked 
[WARNING ] stderr: Traceback (most recent call last): 

[WARNING ] stderr: File "main.py", line 2, in «module» 

[WARNING ] stderr: from designer.app import DesignerApp 

[WARNING ] stderr: File "/Users/cycleuser/kivy-designer/designer/app.py", 
line 27, in «module» 

[WARNING ] stderr: from kivy.garden.filebrowser import FileBrowser 
[WARNING ] stderr: ImportError: No module named filebrowser 


Yep, | found that the filebrowser was missing. So | run: 


xL 9 > filebrowser 没 安 装 是 吧 ， 那 就 安装 咯 。 就 运行 一 下 安装 工具 就 是 了 


kivy -m pip install -U watchdog pygments docutils jedi gitpython six kivy-garden 
garden install filebrowser 


If you run : 


pip install -U watchdog pygments docutils jedi gitpython six kivy-garden 


instead of 


而 没 注 意 官 方 告诉 的 要 运行 


kivy -m pip install -U watchdog pygments docutils jedi gitpython six kivy-garden 


you may waste a lot of time... Because you can still run 


这 样 就 会 浪费 好 多 时 间 。。。 因为 两 种 方式 安装 之 后 ， 会 发 现 都 能 运行 下 面 的 命令 来 安 
X filebrowser : 


garden install filebrowser 


But the location of garden would be in the user path of "~/.kivy/garden" instead of the right 
location as below: 





但 安装 位 置 是 不 一 样 的 ! ! ! 如果 像 我 那样 安装 就 跑 到 用 户 目录 下 面 安 装 了 ， 而 不 是 安 
装 在 正确 位 置 ， 下 面 的 位 置 是 正确 位 置 : 


/Applications/Kivy.app/Contents/Resources/.kivy 


The kivy.app run when you type " kivy main.py " from the location below: 


43447 kivy.app 的 时 候 ， 跑 的 是 kivy.app 路 径 里 面 的 Python， 也 会 在 这 个 里 面 找 
filebrowser， 如 果 安 装 到 用 户 路 径 去 了 ， 当 然 就 找 不 到 了 啊 : 


/Applications/Kivy.app/Contents/Resources/.kivy 


So if you install garden and filebrowser in the home dir, you can copy the garden dir from " 
~/.kivy " to " /Applications/Kivy.app/Contents/Resources/.kivy ". 





所 以 如 果 你 跟 我 一 样 安装 到 用 户 目 录 了 ， 就 把 东西 从 " ~/.kivy "复制 到 " 
/Applications/Kivy.app/Contents/Resources/.kivy "就 可 以 了 。 


Then try to run "kivy main.py" and everything is OK now. 
然后 再 运行 "kivy main.py"， 就 发 现 可 以 跑 界 面 设计 工具 了 。 


Always remember to add "kivy -m " before "pip install"! | hope that this could help other on 
similar problems. 


一 定 要 记 住 ， 在 "pip install" 的 前 面 要 添加 "kivy -m"， 这 样 才 能 安装 到 Kivy.app 的 路 径 

内 ， 而 不 是 系统 路 径 中 | 唉 ， 项 望 能 帮助 其 他 遇 到 类 似 问 题 的 小 伙伴 吧 。 
| hope kivy can give a tip about the location of garden installed so we careless people may 
save a lot of time. 


其 实 安装 garden 的 时 候 kivy 如 果 能 给 提示 一 下 安装 路 径 该 有 多 好 ， 这 样 起 码 容易 注意 
到 这 个 问题 了 。 


Bug-Garden on Mac 
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